Implementarea unei integrări Batch

Cerințe preliminare

  • Asigurați-vă că profilul dvs. comerciant este activat pentru serviciul de Batch.
  • Înainte de a începe integrarea, consultați Bune practici și Sfaturi.

Pași pentru integrare

Pasul 1: Accesați gateway-ul

Ca prim pas, verificați-vă conectivitatea la eGenius Platform

Pasul 2: Cunoașterea câmpurilor de introducere date

Înainte de a începe să construiți integrarea de testare, trebuie să aveți pregătite valorile câmpurilor care necesită introducerea de date de către dvs.

Pasul 3: Crearea unei solicitări pentru lot

Crearea corpului solicitării este un pas critic pentru integrare.

Pasul 4: Trimiterea unei solicitări pentru lot

Pentru trimiterea securizată a corpului solicitării de tranzacție către eGenius Platform, sunt necesare mai multe elemente.

Pasul 5: Recepționare stare lot

După ce un lot a fost trimis, puteți solicita periodic informații despre starea lotului pentru a afla starea curentă a procesării lotului.

Pasul 6: Procesare răspuns pentru lot

După finalizarea procesării unui lot, puteți solicita un fișier răspuns care conține rezultatul fiecăreia dintre operațiunile încărcate.

Pasul 7: Testare și activare

Testarea vă permite să verificați dacă integrarea dvs. funcționează în modul dorit.

Depanare și întrebări frecvente

Pot utiliza mai multe profiluri comerciant în cadrul unei singure solicitări pentru lot?

Da, puteți utiliza mai multe profiluri comerciant într-o singură solicitare pentru lot, dacă puteți asigura faptul ca acreditările de operațiune (identificatorul comerciantului și parola de autentificare) pentru fiecare înregistrare de rând de operațiune sunt valide pentru a asigura autentificarea și autorizarea cu succes.

Implicit, acreditările pentru operațiune, pentru fiecare operațiune dintr-un lot vor utiliza acreditările de autentificare furnizate în antetul de solicitare pentru lot (atât identificatorul comerciantului cât și parola). Puteți opta să utilizați mecanismul implicit sau să furnizați acreditări de operațiune pentru fiecare înregistrare de rând de operațiune. Cu ultima dintre opțiuni, autentificarea pentru operațiune va utiliza acreditările de nivel de operațiune și nu va utiliza acreditările implicite utilizate pentru încărcarea lotului. Dacă, acreditările de nivel operațiune sunt incorecte, atunci lotul încărcat va fi respins.

În exemplul de fișier de lot de mai jos, operațiunile VOID vor utiliza acreditările din antetul solicitării de lot, deoarece identificatorul și parola comerciantului nu au fost furnizate.

merchant,apiPassword,apiOperation,order.id,transaction.id,transaction.amount,transaction.currency,
cardDetails.card.number, 
cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,result,error.cause, error.explanation,response.gatewayCode
TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,,
TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104168,TXID1,30,AUD,5123456789012346,05,13,,,,,
TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104169,TXID1,100,AUD,345678901234564,05,13,,,,,
,,VOID,1256378915689,TXID1,100,AUD,4987654321098769,05,13,,,,,
,,VOID,1256378915690,TXID1,100,AUD,4987654321098769,05,13,,,,,
,,VOID,1256378915691,TXID1,100,AUD,4987654321098769,05,13,,,,,
Care sunt cauzele posibile pentru eșecul trimiterii unui lot?

Trimiterea unui lot poate eșua din cauza următoarelor erori.

Scenariu Mesaj de eroare
Lot incomplet deoarece asimilarea mesaj SHA-1 nu este corespunzătoare Trimiterea lotului a eșuat din cauza unuia dintre următoarele motive:
  • Codul MIC trimis nu corespunde codului MIC calculat pentru fișierul de lot primit.
  • Codul MIC nu are realizat hașul pe baza algoritmului SHA-1.
  • Codificarea MIC nu este HEX.
  • Nu a fost furnizat niciun cod MIC în corpul solicitării.
Vă rugăm să verificați solicitarea și să încercați să trimiteți din nou lotul.
Nume lot dublat
  • A fost deja încărcat și validat un lot cu același nume dar conținut diferit.
  • Este în curs de încărcare un lot cu același nume.
Trimiterea lotului a eșuat: Un lot cu acest nume se încarcă în acest moment sau un lot cu acest nume, dar conținut diferit a fost deja încărcat. Dacă fișierul este deja în curs de încărcare, vă rugăm să așteptați până la finalizarea încărcării. Dacă utilizați un nume de fișier care este deja folosit, vă rugăm să redenumiți fișierul și să trimiteți din nou.
Dacă nu aveți suficiente drepturi pentru a trimite loturi, este returnată o eroare de autentificare:
  • Comerciantul nu are dreptul "API și Loturi găzduite"
  • ID comerciant nevalid
  • Parolă incorectă
Autentificare eșuată: Acreditările furnizate în înregistrarea <record number> sunt incorecte. Aceasta situație poate avea următoarele cauze:
  • Este furnizat un ID de comerciant, dar comerciantul nu are suficiente drepturi pentru a trimite loturi pentru procesare.
  • ID comerciant este incorect.
  • Parola furnizată este incorectă.
Vă rugăm să corectați acreditările și să vă asigurați că, comerciantul are suficiente drepturi pentru a trimite loturi pentru procesare, apoi încercați să trimiteți din nou solicitarea.
Dacă la nivel de operațiune furnizați numai parola și nu și ID comerciant, este returnată o eroare de autentificare. Autentificare eșuată. În înregistrarea <record number> fișierului de lot, este furnizată o parolă, dar nu și un ID de comerciant. Vă rugăm, fie să adăugați un ID comerciant, fie să eliminați parola pentru a utiliza acreditările comerciant de nivel lot pentru această înregistrare, apoi încercați să trimiteți din nou solicitarea.
Dacă acreditările de lot sunt formatate incorect, este returnată o eroare de autentificare. Autentificare eșuată: Acreditările furnizate în antet fie:
  • utilizează un caracter nevalid
  • utilizează o codificare Base 64 nevalidă
  • depășesc lungimea de 70 de caractere.
Vă rugăm să corectați solicitarea și apoi să încercați să trimiteți din nou.
Este returnată o eroare de autentificare dacă:
  • Acreditările lotului sunt nevalide
  • Comerciantul nu are dreptul "API și Lot"
  • Câmpul ID comerciant este gol
  • ID comerciant este incorect
  • Câmpul parolă este gol
  • Parola este incorectă
Autentificare eșuată: Acreditările furnizate pentru lot sunt nevalide. Vă rugăm să corectați acreditările și să încercați să trimiteți din nou solicitarea.
Dacă antetul conține caractere nevalide, este returnată o eroare de analiză. Trimiterea lotului a eșuat: Lotul nu a putut fi analizat deoarece antetul conține un caracter nevalid. Caracterele permise sunt:
  • Alfanumeric (a-z, A-Z, 0-9)
  • Punct (.)
  • Paranteze pătrate ([ ])
Vă rugăm să corectați numele din antet și să vă asigurați că utilizați codificarea corectă, apoi încercați să trimiteți din nou lotul.
Este returnată o eroare de analiză dacă o înregistrare de rând de operațiune conține mai multe valori decât cele definite în antet. Trimiterea lotului a eșuat: Lotul nu a putut fi analizat, deoarece înregistrarea <record number> conține mai multe valori decât cele definite în antet. Vă rugăm să corectați lotul și apoi să încercați să trimiteți din nou.
Dacă dimensiunea maximă individuală a unui câmp este depășită sau dacă este întâlnită o eroare necunoscută de analiză la citirea unei înregistrări de operațiune, este returnată o eroare de analiză. Trimiterea lotului a eșuat: Lotul nu a putut fi analizat, din cauza unei erori în înregistrarea <record number>. Vă rugăm să vă asigurați că lotul se conformează formatului de fișier și că utilizați codificarea corectă, apoi încercați să trimiteți din nou lotul.
Dacă nu este furnizată o codificare, sau este furnizată o codificare neacceptată, este returnată o eroare de codificare. Solicitarea a eșuat: Codificarea furnizată nu este acceptată. Codificările acceptate sunt UTF-8 și LATIN1. Vă rugăm să trimiteți din nou solicitarea folosind o codificare acceptată.
Lotul nu a putut fi găsit. Solicitarea a eșuat: Nu a putut fi găsit un lot cu acest nume de lot.
Vă rugăm să corectați numele de lot și să trimiteți din nou solicitarea.
Verificarea de lungime pentru versiunea furnizată a eșuat. Solicitarea a eșuat: Versiunea furnizată nu este validă. Vă rugăm să corectați versiunea și să trimiteți din nou solicitarea.
Verificarea lungimii pentru Numele de lot furnizat a eșuat. Solicitarea a eșuat: Numele de lot furnizat nu este valid. Vă rugăm să corectați numele de lot și să trimiteți din nou solicitarea.
Verificarea de lungime pentru ID comerciant furnizat a eșuat. Solicitarea a eșuat: ID comerciant furnizat nu este valid. Vă rugăm să corectați ID comerciant și să trimiteți din nou solicitarea.
A apărut o eroare de gateway Solicitarea nu a putut fi trimisă către Gateway din cauza unei erori interne a Gateway-ului. Vă rugăm să încercați din nou mai târziu.
Sun operațiunile eșuate dintr-un fișier de lot încercate din nou?

Procesarea operațiunilor de către Batch poate eșua din cauza unei erori de comunicație sau de sistem, având ca rezultat una dintre erorile următoare:

  • A apărut o eroare din cauza unei erori interne a sistemului.
  • A apărut o eroare din cauza faptului că serverul are insuficiente resurse pentru a procesa solicitarea în acest moment.
  • A apărut o eroare în decursul procesării unei tranzacții de verificare a Tokenization

Dacă aceasta apare și o operațiune poate fi încercată din nou, Batch va încerca din nou să trimită operațiunea pentru procesare, până fie este primit un răspuns pentru operațiune care nu poate fi încercat din nou fie este atinsă limita numărului de încercări.

Ce se întâmplă când încarc un nume de lot dublu cu același conținut sau cu un conținut diferit?

Batch stochează numele de loturi și codurile MIC (Cod de integritate mesaj) corespunzătoare acestora încărcate de către dvs. Loturile cu un nume de lot care a fost trimis anterior, dar care au un conținut diferit, pot fi identificate și vor fi respinse de Batch.

Loturile cu același nume și conținut cu un lot trimis anterior pot fi, de asemenea, identificate, și Batch returnează aceeași stare ca cea a lotului încărcat anterior. Deci, în cazul în care comerciantul bănuiește că a existat o problemă de transmisie, acesta poate verifica dacă lotul a fost încărcat cu succes în Batch.

Dacă este trimis un nume de lot duplicat cu un conținut diferit sau dacă lotul prezent este încărcat în timp ce primul lot încă se încarcă, este returnat codul HTTP de stare 409 și un mesaj de eroare.
De ce primesc eroarea HTTP cu codul 400, Format nevalid antet?

Valorile din linia de antet a unei solicitări pentru lot trimise pentru procesare pot conține numai caracterele care pot fi găsite în numele de câmpuri NVP API. Următoarele caractere sunt permise:

  • Alfanumeric (a-z, A-Z, 0-9)
  • Punct (.)
  • Paranteze pătrate ([ ])
De ce primesc o eroare de analiză când trimit un lot pentru procesare?

Batch respinge un lot dacă sunt întâlnite erori de analiză. Analiza include despărțirea unui lot în rânduri și a liniilor în câmpuri.

Erorile de analiză pot apărea atunci când:

  • o înregistrare de operațiune are mai multe virgule decât ceea ce este inclus în înregistrarea antet
  • este depășită dimensiunea maximă individuală a unui câmp

Trebuie să corectați aceste erori înainte de a trimite lotul din nou pentru procesare.

Bune practici și sfaturi

Este garantat că ordinea în care sunt specificate operațiunile într-un fișier de lot va fi ordinea de procesare?

Serviciul Batch nu garantează că va procesa operațiunile în aceeași ordine ca cea specificată în fișierul de lot, deoarece dispecerul Batch poate procesa operațiuni în paralel. Această modalitate de operare poate fi atribuită, de asemenea, funcției de reîncercare, adică, dacă unele operațiuni din fișierul de lot necesită o reîncercare, atunci operațiunile care sunt pregătite vor fi procesate mai întâi, indiferent de ordinea în care sunt specificate. De exemplu, chiar dacă operațiuni ulterioare sunt specificate după operațiuni inițiale (Capture urmată de o Authorization, Void urmată de Pay), atunci Capture poate fi realizată înainte de Authorization sau Void înainte de Pay.

Prin urmare, pentru operațiunile care trebuie să urmeze strict o ordine, este recomandată rularea lotului inițial de operațiuni mai întâi, așteptați fișierul de răspuns pentru lot și dacă acesta a avut succes rulați lotul ulterior de operațiuni.

Cum pot utiliza Tokenization cu Batch?

Tokenization stochează detaliile cardului într-un token. Pentru a utiliza Tokenization cu Batch trebuie să utilizați identificatorul simbolului în cadrul fișierului de lot, ca în exemplul prezentat mai jos.

apiOperation,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,cardDetails.card.securityCode,cardDetails.cardToken,transaction.amount,transaction.currency,transaction.id,transaction.authorizationCode,order.id,card.start.month,card.start.year,card.issueNumber,card.bankAccountType
AUTHORIZE,,,,,200,10,AUD,TXID1,,10323711802,,,,
AUTHORIZE,,,,,300,20,AUD,TXID1,,10323711803,,,,
AUTHORIZE,,,,,400,10,AUD,TXID1,,10323711804,,,,
AUTHORIZE,,,,,500,5.99,AUD,TXID1,,10323711805,,,,
Este necesar să furnizez acreditările de operațiune pentru fiecare înregistrare de rând de operațiune dintr-un fișier de lot?

Acreditările de operațiune includ identificatorul comerciantului și parola. Acreditările de operațiune, pentru fiecare operațiune dintr-un lot, vor utiliza implicit acreditările de autentificare furnizate în antetul de solicitare pentru lot (atât identificatorul comerciantului, cât și parola). Totuși, dacă specificați valori pentru aceste două câmpuri pentru înregistrări de rând de operațiune, autentificarea pentru operațiune va utiliza acreditările de nivel de operațiune și nu va utiliza acreditările implicite utilizate pentru încărcarea lotului.

În cazul existenței mai multor profiluri comerciant, puteți alege ca implicit să se recurgă la acreditările de autentificare furnizate cu antetul de solicitare pentru lot și/sau să furnizați acreditări de operațiune pentru unul sau mai multe profiluri comerciant.
Dacă doriți să utilizați acreditări de nivel de operațiune, trebuie să furnizați ATÂT identificatorul comerciantului, CÂT ȘI acreditările, pentru fiecare înregistrare de rând de operațiune, nu doar unul sau celălalt. Dacă nu sunteți autorizat să utilizați serviciul Lot sau dacă acreditările de nivel de operațiune sunt incorecte, atunci încărcarea lotului va fi respinsă. Dacă doriți ca implicit să fie utilizate acreditările din antetul de solicitare pentru lot, nu le includeți în solicitare.
Pot procesa mai multe tipuri de operațiuni (Pay, Refund, Auth, Capture, Void etc.) într-un singur fișier de lot?

Da, puteți procesa mai multe tipuri de operațiuni într-un singur fișier de lot, cu condiția ca acestea să NU fie asociate aceleiași comenzi, respectiv să nu conțină același identificator de comandă. Serviciul Batch nu garantează că va procesa operațiunile în aceeași ordine ca cea specificată în fișierul de lot, deoarece dispecerul Batch poate procesa operațiuni în paralel. Această modalitate de operare poate fi atribuită, de asemenea, funcției de reîncercare, adică, dacă unele operațiuni din fișierul de lot necesită o reîncercare, atunci operațiunile care sunt pregătite vor fi procesate mai întâi, indiferent de ordinea în care sunt specificate. De exemplu, dacă operațiuni Pay și Void sunt în același fișier de lot, operațiunea Void poate fi realizată înaintea operațiunii Pay. Totuși, dacă operațiunile NU sunt asociate aceleiași comenzi, respectiv în cazul în care conțin identificatoare de comandă diferite, atunci puteți avea mai multe tipuri de operațiuni într-un singur fișier de lot.

Pot utiliza mai multe surse de detalii card în cadrul unui singur fișier de lot?

Da, puteți utiliza mai multe surse de detalii card într-un singur fișier de lot, cu excepția identificatorului sesiunii de plată. Pentru informații despre surse multiple, consultați Surse multiple de detalii card.

Operațiunile Authorize din exemplul de mai jos utilizează simboluri în locul detaliilor cardului.

apiOperation,order.id,transaction.id,transaction.amount,transaction.currency,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,cardDetails.cardToken,result,error.cause,error.explanation,response.gatewayCode
PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,,,
PAY,921830104168,TXID1,50,AUD,5123456789012346,05,13,,,,,,
PAY,921830104169,TXID1,100,AUD,4987654321098769,05,13,,,,,,
AUTHORIZE,10072028281,TXID1,,,,,,,200,,,,,
AUTHORIZE,10072028282,TXID1,,,,,,,300,,,,,
AUTHORIZE,10072028283,TXID1,,,,,,,400,,,,,

Copyright © 2021 UniCredit Bank