Operațiuni tranzacții

Dacă sunteți integrat(ă) pe gateway prin API, puteți utiliza operațiunile API pentru a procesa tranzacții, a reapela detaliile tranzacțiilor, a stoca detaliile cardurilor etc. Pentru a efectua o operațiune, trebuie să aveți privilegiul corespunzător în profilul dvs. de comerciant de pe gateway. Pentru a afla ce operațiuni sunt disponibile pentru dvs., contactați furnizorul de servicii de plată.

Funcționalitatea disponibilă pentru dvs. depinde de capabilitățile achizitorilor configurați în profilul dvs. de comerciant de pe gateway. Dacă o funcționalitate nu este acceptată pentru achizitor pe gateway, orice solicitări de operațiuni pentru executarea funcționalității respective vor fi respinse de gateway pentru achizitorul respectiv.
Dacă sunt acceptate, detaliile de plată din solicitările de tranzacții pot fi furnizate din mai multe surse. Surse multiple de detalii de plată

Operațiunile pentru tranzacțiile inițiale

Această secțiune descrie operațiunile pe care le puteți utiliza pentru a iniția o tranzacție.

Authorize

Operațiunea Authorize verifică detaliile cardului plătitorului, se asigură că plătitorul are fonduri suficiente în linia de credit și încearcă să rezerve fondurile solicitate. Limita de credit a plătitorului este redusă cu suma autorizată, iar fondurile sunt rezervate pe o perioadă de timp (în majoritatea cazurilor, 5–8 zile), în funcție de schema cardului și regulile de emitere a cardului plătitorului.

Autorizarea nu debitează fonduri din contul plătitorului, dar rezervă întreaga valoare a comenzii, pregătită pentru operațiunea Capture prin care se debitează cardul și se transferă fondurile în contul dvs. În extrasul de cont al plătitorului nu apar tranzacțiile Authorize, ci numai tranzacțiile Capture.

Pentru efectuarea cu succes a autorizării, gateway-ul returnează valoarea result=SUCCESS în răspunsul la tranzacție. Puteți utiliza Authorize ca operațiune ulterioară doar dacă tranzacția inițială este Verify și dacă detaliile cardului din solicitarea Authorize și cele din tranzacția Verify corespund.

Operațiunea Authorize mai este denumită, de asemenea, "Auth", "Authorization".

Pentru anumite plăți prin browser, puteți utiliza o operațiune Authorize folosind operațiunea Initiate Browser Payment. Pentru mai multe informații, consultați secțiunea Implementarea unei integrări pentru plată prin browser.

Siguranță comandă

Puteți indica un nivel de certitudine al sumei autorizate, care va fi decontată prin furnizarea câmpului order.certainty în solicitarea Authorize. În acest scop, trebuie să aveți privilegiul „Schimbare certitudine comandă” activat în profilul dvs. de comerciant de către furnizorul de servicii de plată. Puteți seta câmpul la oricare dintre următoarele valori:

  • FINAL: Suma autorizată finală va fi, în mod normal, decontată printr-una sau mai multe decontări, în intervalul de timp stabilit (în mod normal, 7 zile). Comanda va fi anulată numai în circumstanțe excepționale (de exemplu, dacă plătitorul își anulează achiziția). Furnizarea acestei valori în tranzacția dvs. poate face ca tranzacția să fie eligibilă pentru comisioane de procesare mai reduse.
  • ESTIMATED: Suma autorizată este o estimare a sumei care va fi decontată în intervalul de timp prevăzut (în mod normal, 30–31 de zile). Este posibil ca suma decontată să fie mai mică sau să nu fie decontată deloc, sau ca autorizarea să fie anulată. Furnizarea acestei valori în tranzacția dvs. poate face ca tranzacției să îi fie aplicate comisioane de procesare mai mari.

Solicitarea este respinsă dacă nu aveți privilegiul de a schimba certitudinea comenzii, iar valoarea introdusă în acest câmp nu corespunde valorii implicite a certitudinii comenzii, configurată în profilul dvs. de comerciant.

Referință API Authorize [REST][NVP]

Expirarea autorizărilor

Autorizările au o perioadă de valabilitate, după care expiră. Perioada de valabilitate a autorizărilor (în milisecunde) poate fi configurată în gateway pentru o combinație de achizitor, tip de card și certitudine a comenzii.

Atunci când trimiteți o solicitare de autorizare către gateway, acesta determină data și ora de expirare a autorizării pe baza perioadei de valabilitate configurate pentru autorizare (folosind combinația dintre tipul de card, achizitor și certitudinea comenzii). Dacă această funcție este acceptată pentru achizitor, expirarea autorizării este returnată în câmpul authorizationResponse.autoExpiry din răspunsul operațiunii Retrieve Transaction. Acest câmp conține data și ora la care gateway-ul va seta automat expirarea autorizării.

După expirarea perioadei de valabilitate a autorizării, gateway-ul va:

  • respinge orice solicitări de decontare bazate pe comandă
  • încerca automat să anuleze autorizarea și să retrimită fondurile la plătitor (dacă această funcție este acceptată pentru achizitor). În acest scop, trebuie să aveți privilegiul „Activare inversări automate autorizare” activat în profilul dvs. de comerciant de către furnizorul de servicii de plată.

    În cazul în care comanda a fost deja capturată parțial și dacă achizitorul acceptă anularea autorizărilor pentru capturi parțiale, gateway-ul va încerca să anuleze/să inverseze suma autorizată decontată.

Actualizare autorizare

Gateway-ul vă permite să extindeți valabilitatea autorizării și să măriți sau să micșorați opțional suma autorizată pentru autorizările valide, dacă achizitorul acceptă acest lucru. În acest scop, trebuie să aveți privilegiul „Update Authorization” activat în profilul dvs. de comerciant de către furnizorul de servicii de plată. Pentru mai multe informații, consultați Update Authorization.

Întrebări frecvente

Ce se întâmplă dacă doresc doar decontarea parțială a autorizării mele?

Atunci când trimiteți o solicitare Capture pentru o comandă, puteți introduce o sumă Capture mai mică decât suma autorizată pentru comandă (order.AuthorizedAmount).

Dacă nu intenționați să decontați suma autorizată rămasă, puteți anula suma autorizată decontată dacă achizitorul acceptă acest lucru.

Este recomandat să integrați versiunea API v50 sau mai recentă, pentru a anula autorizările comenzilor decontate parțial.

Puteți introduce numărul prevăzut de operațiuni Capture pentru comandă în câmpul order.expectedNumberOfCaptures din solicitarea Capture sau din interfața cu utilizatorul din Administrare cont comerciant. În cazul în care numărul total de decontări pentru comandă (inclusiv decontarea curentă) este mai mare sau egal cu numărul total prevăzut de solicitări Capture, gateway-ul va declanșa automat anularea sumei autorizate decontate, dacă acest lucru este acceptat pentru achizitor.

Câmpul order.expectedNumberOfCaptures poate fi trimis numai începând cu versiunea 44 a API.
Ce se întâmplă dacă nu mai doresc să decontez o autorizare?

Puteți anula autorizarea trimițând o solicitare VOID cu ID-ul de tranzacție pentru autorizarea care va fi anulată în câmpul transaction.targetTransactionId.

Ce se întâmplă trebuie să decontez o sumă mai mare decât cea autorizată?

Pentru a deconta o sumă mai mare decât cea autorizată pentru o comandă, profilul dvs. de comerciant de pe gateway trebuie activat pentru dreptul Decontare în exces. Consultați Decontările în exces

Pot deconta o autorizare efectuată în afara gateway-ului?

Da, aceasta este numită solicitare de Standalone Capture și, dacă este acceptată pentru achizitor, puteți trimite o simplă solicitare de decontare cu codul de autorizare returnat de achizitor (în răspunsul de autorizare).

Pay

Operațiunea Pay combină funcțional o operațiune Authorize și una Capture într-un singur mesaj. O singură tranzacție autorizează plata și transferă fondurile din contul plătitorului în contul dvs.

Dacă doriți ca următoarea operațiune trimisă să fie Pay, trebuie să aveți o tranzacție de verificare efectuată cu succes, iar detaliile cardului din solicitarea Pay și cele din tranzacția Verify trebuie să corespundă.

Nivelul de certitudine al comenzii pentru o tranzacție Pay este setat la FINAL. Pentru mai multe informații, consultați Certitudinea comenzilor.

Operațiunea Pay mai este denumită, de asemenea, "Sale", "Purchase".

În cazul anumitor plăți prin browser (de exemplu, PayPal, Giropay, Sofortbanking etc.), puteți iniția o operațiune Pay utilizând operațiunea Initiate Browser Payment. Pentru mai multe informații, consultați secțiunea Implementarea unei integrări pentru plată prin browser.

Referință API Pay [REST][NVP]

Auto Capture

Auto-capture este o variantă a operațiunii Pay care permite unui comerciant care are dreptul de a efectua tranzacții Pay și utilizează un achizitor care acceptă numai tranzacțiile Authorize/Capture să efectueze o operațiune Authorize, urmată de o operațiune Capture declanșată automat. În cazul acestui tip de tranzacție, solicitarea Pay este transformată în operațiuni Authorize și Capture.

Această operațiune poate fi realizată utilizând modelele de integrare Direct Payment, Hosted Session sau Batch.

Identificatorul de tranzacție pentru ambele solicitări, Authorize și Capture, va fi identificatorul de tranzacție furnizat de către dvs. în solicitarea inițială Pay. În răspunsul Pay, câmpul transaction.type va indica ultima tranzacție încercată pentru a realiza solicitarea, adică Authorize sau Capture.

Puteți utiliza operațiunea Colectare pentru a colecta rezultatul unei operațiuni Decontare automată. Este returnat rezultatul ultimei tranzacții încercate pentru realizarea solicitării.

Puteți anula o tranzacție Pay decontată automat folosind operațiunea Void Pay. Când realizați această operațiune, serviciul eGenius Platform:

  • încearcă o „Void Capture” pentru tranzacția Capture.
  • dacă operațiunea „Void Capture” are succes, este încercată o „Void Authorization” pentru Authorization. Dacă operațiunea „Void Capture” eșuează, răspunsul va indica faptul că anularea a eșuat; nu mai este încercată operațiunea Void Authorization.
Auto-Capture poate fi realizată, de asemenea, pentru o tranzacție Authorize recomandată, furnizând codul manual de autorizare.
Verify

Operațiunea Verify vă permite să verificați detaliile contului plătitorului înainte de a realiza tranzacția Pay sau Authorize. Aceasta verifică detaliile plății utilizând metoda de verificare acceptată de achizitor. De exemplu, dacă achizitorul acceptă Serviciul de verificare a adresei (AVS), atunci Verify trimite o tranzacție Numai AVS, cu suma tranzacției egală cu zero și detaliile de adresă ale plătitorului.

Referință API verificare [REST][NVP]

Standalone Capture

O tranzacție de Standalone Capture este o tranzacție Capture în care autorizarea a avut loc în afara gateway-ului. Când trimiteți o tranzacție de Standalone Capture către gateway, trebuie să furnizați codul de autorizare generat extern în câmpul transaction.authorizationCode și să completați celelalte câmpuri obligatorii.

Puteți trimite Standalone Capture dacă aveți dreptul Capture activat pentru profilul dvs. de comerciant.

Codul de autorizare este opțional pentru tranzacțiile cu sursă a tranzacției „CARD_PRESENT”. Acest lucru permite realizarea unei Standalone Capture pentru plățile cu card prezent autorizate offline.

Referință API Standalone Capture [REST][NVP]

Standalone Refund

O tranzacție de Standalone Refund este o tranzacție de Refund care vă permite să transferați fonduri din contul dvs. înapoi plătitorului, fără o achiziție anterioară. Rambursările independente pot fi efectuate când doriți să creditați contul plătitorului fără a asocia creditul cu o tranzacție anterioară.

Referință API Standalone Refund [REST][NVP]

Operațiuni ulterioare

Această secțiune descrie operațiunile pe care le puteți realiza asupra tranzacțiilor inițiale Authorize sau Pay.

Pentru a verifica ce operațiuni sunt configurate pentru profilul dvs. de comerciant, contactați furnizorul de servicii de plată.

Operațiunile ulterioare sunt acceptate prin intermediul modelelor de integrare Direct Payment sau Batch.
Update Authorization

Operația Update Authorization vă permite:

  • Să extindeți perioada de valabilitate a unei autorizări existente,
  • Să măriți sau să micșorați opțional suma autorizată.

Dacă doriți doar să extindeți perioada de autorizare, nu remiteți transaction.amount în solicitare. Data și ora actualizate de expirare a autorizării sunt returnate în câmpul authorizationResponse.autoExpiry din răspunsul Retrieve Transaction. Este recomandat să remiteți solicitarea Update Authorization în intervalul de validitate a autorizării originale.

Dacă furnizați o sumă de tranzacție care este mai mare decât suma autorizării existente, suma autorizată este actualizată la noua valoare. De exemplu, dacă suma autorizată existentă este de 100 USD, însă valoarea tranzacției introdusă în solicitarea Update Authorization este de 120 USD, noua sumă autorizată disponibilă pentru decontare va fi de 120 USD.

Dacă furnizați o sumă de tranzacție care este mai mică decât suma autorizării existente, suma autorizată este actualizată la noua valoare. De exemplu, dacă suma autorizată existentă este de 100 USD, însă valoarea tranzacției introdusă în solicitarea Update Authorization este de 80 USD, noua sumă autorizată disponibilă pentru decontare va fi de 80 USD. Gateway-ul procesează automat o solicitare de anulare pentru suma autorizată rămasă, de 20 USD (dacă achizitorul acceptă acest lucru).

Rețineți că gateway-ul poate actualiza o autorizare existentă numai dacă sunt îndeplinite următoarele condiții:

  • Profilul dvs. de comerciant de pe gateway trebuie să fie activat pentru dreptul „Update Authorization” de către furnizorul de servicii de plată.
  • Moneda comenzii trebuie să corespundă monedei autorizării existente.
  • Autorizarea existentă trebuie să fie validă, efectuată cu succes și complet aprobată.
În cazul tranzacțiilor Mastercard, mărirea sumei de autorizare extinde automat și perioada de valabilitate a autorizației.

Totaluri comenzi

După o solicitare Update Authorization trimisă cu succes (pentru un card sau PayPal), valoarea comenzii (order.amount) și suma totală autorizată (order.totalAuthorizedAmount) sunt actualizate la valoarea tranzacției Update Authorization (transaction.amount). Aceasta se aplică indiferent dacă tranzacția Update Authorization a fost trimisă către achizitor sau aprobată automat de gateway (response.gatewayCode=APPROVED_AUTO). Dacă, însă, decideți să evitați actualizarea autorizării pentru o solicitare de decontare în exces (trimițând transaction.authorizationAdjustmentActions=NO_ACTION, a se vedea Decontările în exces), iar gateway-ul trimite o decontare în exces către achizitor, totalurile comenzii NU sunt actualizate.

Aprobarea automată a solicitărilor Update Authorization de către gateway (response.gatewayCode=APPROVED_AUTO) se aplică numai atunci când suma furnizată este mai mare decât cea autorizată existentă.

Subtotaluri comenzi

În solicitarea Update Authorization pentru plăți cu cardul sau prin PayPal, puteți furniza următoarele valori de subtotaluri:

  • order.itemAmount
  • order.shippingAndHandlingAmount
  • order.taxAmount
  • order.discount.amount (numai pentru plățile cu cardul)
  • order.gratuityAmount (numai pentru plățile cu cardul)
Furnizarea order.cashbackAmount în solicitarea Update Authorization nu este acceptată.

Gateway-ul NU efectuează validarea dacă suma subtotalurilor este egală cu transaction.amount (respectiv, order.amount); totuși, acest lucru trebuie asigurat pentru plățile PayPal.

Comisionarea

În solicitarea Update Authorization, puteți actualiza valoarea unui comision folosind oricare dintre câmpurile de mai jos:

  • order.surchargeAmount: Utilizați acest câmp dacă furnizați o valoare calculată în prealabil a comisionului.
  • order.netAmount: Utilizați acest câmp dacă gateway-ul calculează valoarea comisionului (pe baza regulilor dvs. pentru comisioane).
Pentru plățile prin PayPal, furnizarea order.surchargeAmount nu este acceptată, iar solicitările care conțin acest câmp vor fi respinse. Dacă furnizați order.netAmount pentru o plată prin PayPal, tranzacția va fi procesată fără aplicarea unui comision.

Referință API Update Authorization [REST][NVP]

Capture

Operațiunea Capture utilizează o autorizare obținută după operațiunea Authorize inițială pentru a transfera fonduri din contul plătitorului în contul dvs. Operațiunea Capture trebuie să fie precedată întotdeauna de o autorizare realizată cu succes și cel puțin ID-ul autorizării trebuie transmis împreună cu solicitarea Capture. Moneda utilizată la decontarea unei sume trebuie să corespundă monedei utilizate în cadrul tranzacției de autorizare.

Începând cu API versiunea v15, dacă doriți să decontați fonduri pe baza unei autorizări realizate cu succes cu ajutorul gateway-ului, atunci NU furnizați detaliile cardului în cadrul solicitării Capture.

Operațiunile Capture sunt, în mod normal, grupate în loturi de către gateway sau de către gazda achizitorului, astfel încât fondurile nu sunt în realitate transferate până la închiderea lotului, când are loc decontarea.

Operațiunea Capture mai este denumită, de asemenea, "Bill", "Complete".

Decontare în exces

Suma totală pe care o decontați poate depăși suma autorizată inițial, dacă aveți activat pentru profilul dvs. comerciant dreptul de decontare în exces.

Decontare în exces este o variație a decontării, în cazul căreia puteți realiza decontări pentru sume mai mari decât suma autorizată. Valoarea în exces permisă este specificată ca procent din valoarea inițială autorizată și este stabilită de către furnizorul dvs. de servicii de plată.

Când trimiteți o solicitare de decontare în exces, gateway-ul va încerca să actualizeze automat suma autorizată la suma pe care doriți să o decontați. Dacă achizitorul acceptă actualizarea autorizărilor, gateway-ul trimite solicitarea Update Authorization către achizitor. În caz contrar, gateway-ul va aproba automat o actualizare a autorizării (până la limita de decontare în exces configurată pentru profilul dvs. de comerciant).

Trimiteți transaction.authorizationAjustmentAction=NO_ACTION în solicitarea Capture dacă nu doriți ca gateway-ul să încerce să actualizeze autorizarea înainte de a trimite operațiunea Capture către achizitor. Rețineți că, în situațiile în care valoarea autorizată nu corespunde decontării, este posibil ca respectiva comandă să nu beneficieze de protecție la rambursare.

Referință API Capture [REST][NVP]

Refund

Operațiunea Refund vă permite să creditați fonduri pentru o comandă existentă înapoi în contul plătitorului. Operațiuni Refund pot fi realizate numai în cazurile în care a fost realizat un transfer de fonduri fie printr-o operațiune Pay, fie printr-o operațiune Capture. Puteți realiza oricâte tranzacții de rambursare asupra tranzacției originale, dar nu puteți rambursa o sumă mai mare decât suma totală care a fost obținută prin intermediul tuturor tranzacțiilor achiziție sau decontare asociate comenzii.

Rambursările sunt realizate din multe motive, de exemplu, returnarea bunurilor nedorite, incorecte sau defecte.

Începând cu API versiunea v15, dacă doriți să rambursați pe baza unei operațiuni Capture sau Pay realizate cu succes cu ajutorul gateway-ului, atunci NU furnizați detaliile cardului în cadrul solicitării Refund.
Rambursare excesivă

Suma totală rambursată pentru o comandă poate depăși suma care a fost decontată cu succes pentru o comandă, dacă aveți activat pentru profilul dvs. comerciant dreptul de rambursare excesivă.

Suma în exces permisă pentru rambursare pentru o sumă decontată pentru tranzacții API poate fi configurată pentru fiecare monedă în parte în Setări de integrare din Administrare cont comerciant. Dacă nu setați o limită maximă de rambursare excesivă pentru o monedă, rambursările excesive pentru comenzi în acea monedă sunt respinse.

La trimiterea unei rambursări, suma totală rambursată pentru comandă (inclusiv rambursarea încercată) nu trebuie să depășească suma totală decontată pentru comanda cu o valoare mai mare decât suma maximă de rambursare excesivă permisă. De exemplu, dacă trimiteți o rambursare excesivă prin intermediul API pentru o comandă în cazul căreia suma totală decontată este de $100 USD și ați setat limita de rambursare excesivă pentru tranzacții API ca fiind $20 USD, atunci puteți rambursa până la maxim $120 USD.

Această caracteristică este disponibilă pentru comenzi realizate atât prin intermediul Administrare cont comerciant cât și prin intermediul API. Pentru rambursări trimise prin intermediul Administrare cont comerciant, valoarea în exces permisă este verificată pe baza limitei de rambursare setată pentru operator în cadrul Setări operator din Administrare cont comerciant.

Referință API Refund [REST][NVP]

Retrieve Transaction

Operațiunea Retrieve Transaction vă permite să colectați detaliile unei tranzacții utilizând ID comandă și ID tranzacție. Ambele valori sunt obligatorii pentru că ID tranzacție identifică o tranzacție în cadrul unei comenzi.

Referință API Retrieve Transaction [REST][NVP]

Retrieve Order

Operațiunea Retrieve Order vă permite să colectați detaliile unei comenzi și tuturor tranzacțiilor asociate cu respectiva comandă.

Referință API Retrieve Order [REST][NVP]

Void

Operațiunea Void încearcă să elimine/anuleze imediat o solicitare de tranzacție. Operațiunile Void pot fi realizate numai pentru tranzacții care nu au fost încă trimise băncii de către achizitor pentru procesare la finalul zilei. Din momentul în care o tranzacție a fost trimisă de achizitor pentru procesare, trebuie să realizați o operațiune Refund în locul unei operațiuni Void.

Puteți anula tranzacții Authorize, Capture, Pay sau Refund. O anulare realizată asupra unei tranzacții de Authorize va elibera imediat orice fonduri rezervate. În cazul tuturor celorlalte tipuri de tranzacții, anularea va împiedica realizarea transferului fondurilor.

Referință API Void [REST][NVP]

Referral

Operațiunea Referral trimite din nou o tranzacție inițială recomandată (tranzacție Authorizaton sau Pay care a primit răspunsul „Consultați emitentul” de la achizitor) ca nouă tranzacție Authorization sau Pay cu un cod de autorizare obținut de la emitent.

Este posibil ca plătitorului să i se solicite să furnizeze informații suplimentare pentru ca emitentul să aprobe tranzacția și să furnizeze un cod de autorizare/ID autorizare manuală.

Referință API Referral Transaction[REST][NVP]

Copyright © 2021 UniCredit Bank