- Ghid de integrare
- Implementarea unei integrări Batch
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 dvs. de introducere
Î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 în lot
Crearea corpului solicitării este un pas critic pentru integrare.
Pasul 4: Trimiterea unei solicitări în lot
Pentru trimiterea securizată a corpului solicitării de tranzacție către eGenius Platform, sunt necesare mai multe elemente.
Pasul 5: Preluarea stării lotului
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,,,,, ,,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 rezumatul mesajului SHA-1 nu se potrivește | Trimiterea lotului a eșuat din cauza unuia dintre următoarele motive:
|
Nume lot duplicat
|
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:
|
Autentificare eșuată: Acreditările furnizate în înregistrarea <record number> sunt incorecte. Aceasta situație poate avea următoarele cauze:
|
| 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:
|
Este returnată o eroare de autentificare dacă:
|
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:
|
| 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 lotului 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-ul de 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 la 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. |
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 defecțiuni 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.
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.
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. Sunt permise următoarele caractere:
- Alfanumerice (a-z, A-Z, 0-9)
- Punct (.)
- Paranteze pătrate ([ ])
Batch respinge un lot dacă se întâlnesc erori de analiză. Analiza include despărțirea unui lot în rânduri și a liniilor în câmpuri.
Poate apărea o eroare de analiză 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.
Cele mai bune practici și sfaturi
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.
Tokenization stochează detaliile cardului într-un simbol. 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,,,,
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.
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.
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,,,,,