Integrarea Hosted Session Click to Pay
Urmați pașii de mai jos pentru a adăuga Click to Pay (C2P) la integrarea dumneavoastră Hosted Session utilizând SDK Click to Pay și API JavaScript (JS). Puteți găsi un exemplu HTML al unei integrări de bază la sfârșitul acestui subiect.
Pentru mai multe informații despre C2P, testarea integrării finalizate și câteva întrebări frecvente, consultați Click to Pay.
Pasul 1: Crearea și actualizarea unei sesiuni
Creați o sesiune utilizând operațiunea CREATE SESSION. Răspunsul returnează un ID de sesiune pe care trebuie să îl folosiți în cadrul pașilor ulteriori pentru a face referire la sesiune.
Puteți adăuga sau actualiza câmpuri într-o sesiune existentă utilizând operațiunea UPDATE SESSION. Cel puțin următoarele câmpuri sunt obligatorii într-o sesiune:
session.id
Identificatorul sesiunii de plată.order.amount
Valoarea totală a comenzii.order.currency
Moneda comenzii.
CREATE SESSION și UPDATE SESSION sunt operațiuni API pe partea serverului care sunt o condiție prealabilă pentru integrarea cu API-ul JS. Utilizați WS API v62 sau o versiune ulterioară cu JS API.
Pentru exemple de solicitare proprii operațiunilor API pe partea de server, descărcați colecția Postman.
Pasul 2: Includeți API-ul JavaScript Click to Pay în pagina dvs. de plată
Includeți C2P JavaScript SDK (click-to-pay.js) furnizat de eGenius Platform în pagina dvs. de plată adăugând un element de script în elementul head din codul dvs. HTML. Această acțiune plasează un obiect ClickToPay în spațiul de nume al ferestrei.
<script type="text/javascript" src="https://egenius.unicredit.ro/form/static/click-to-pay/click-to-pay.min.js"></script>
Pasul 3: Configurați interacțiunea Click to Pay
Obiectul de configurare vă permite să configurați interacțiunea dintre plătitor și C2P pe pagina dvs. de plată. Când plătitorul este gata să plătească pentru comanda sa și dvs. încărcați pagina de plată, inițiați interacțiunea C2P invocând funcția ClickToPay.configure(). Pentru detalii suplimentare și un exemplu de funcție, consultați Referința API.
Inițializarea bibliotecii C2P poate dura câteva secunde. Inițializați componentele cât mai devreme posibil în timpul încărcării paginii, astfel încât plătitorul să poată finaliza rapid plata folosind C2P.
În funcția ClickToPay.configure(), configurați parametrii, componentele paginii de plată și callback-urile pentru interacțiunea C2P, așa cum este definit în secțiunile următoare.
Parametrii de configurare
Utilizați parametrii pentru a defini detaliile interacțiunii dvs. C2P.
Tabel: Parametrii de configurare
| Câmp | Obligatoriu | Tip | Descriere |
|---|---|---|---|
merchant.id |
Da | șir | ID-ul dvs. de comerciant, utilizat de către gateway pentru a determina opțiunile de plată. |
merchant.name |
Da | șir | Numele dvs. comercial, de exemplu, numele cunoscut de plătitorul dvs. |
merchant.url |
Obligatoriu | Șir URL | Adresa URL a site-ului dvs. web pe care o folosește plătitorul. |
session.id |
Da | șir | ID-ul sesiunii este returnat de la operațiunea CREATE SESSION la Pasul 1. |
session.wsVersion |
Da | int | Versiunea WS API utilizată la trimiterea operației CREATE SESSION la Pasul 1. Valoarea trebuie să fie >= 62. |
order.amount |
Da | șir | Valoare comandă. Valoarea este folosită doar pentru afișare și nu pentru procesarea plății. |
order.currency |
Da | șir | Monedă comandă. Valoarea este folosită doar pentru afișare și nu pentru procesarea plății. |
interaction.billingPreference |
Nu | șir de enumerare | Dacă o adresă de facturare este colectată în timpul interacțiunii C2P. Valorile posibile sunt:
|
interation.collectShippingAddress |
Nu | boolean | Dacă o adresă de livrare este colectată în timpul interacțiunii C2P. Valoarea implicită este false. În mod implicit, plătitorul poate selecta orice țară pentru adresa de livrare. Pentru a restricționa lista de țări în care livrați bunuri, trebuie să vă configurați profilul de comerciant pentru C2P prin Merchant Administration (MA), fie cu o listă de țări permise, fie cu o listă de țări exceptate. Dacă ați definit orice restricție, plătitorul poate selecta doar o țară pentru adresa de livrare permisă. Nu puteți suprascrie țările cu adresele de expediere acceptate pentru solicitare anumită, ci doar pentru toate solicitările din profilul dvs. de comerciant. |
interation.locale |
Nu | șir | Limba folosită în timpul interacțiunii C2P. Implicit, se utilizează limba configurată în browserul plătitorului. În cazul în care limba plătitorului nu poate fi determinată sau nu este acceptată, valoarea implicită en_US este folosită cu excepția cazului în care furnizați o valoare diferită pentru acest parametru.
|
interation.country |
Nu | șir | Conținut specific țării, cum ar fi Termenii și condițiile, prezentat plătitorului în timpul interacțiunii C2P. Valoarea pe ați configurat-o în profilul dvs. de comerciant din gateway este folosită implicit. Dacă doriți să înlocuiți această valoare pentru această interacțiune, setați acest parametru la o valoare de țară validă ISO 3166 alpha-3. |
interaction.cardSelectionAction |
Nu | șir | Acțiune care trebuie efectuată atunci când plătitorul face selecția cardului. Valorile posibile sunt:
|
interaction.skipDCFInteraction |
Nu | Boolean | Dacă plătitorul trebuie să își confirme manual adresa de e-mail și numărul de telefon. Acest lucru se aplică doar înregistrării cardului Mastercard în acest moment. Parametrii customer.email și customer.mobilePhone sunt necesari în cadrul funcției configure() pentru ca această caracteristică să aibă efect.Dacă se setează la true, plătitorul nu este solicitat cu un mesaj Confirmă pe componenta DCF (Interfață de utilizator Digital card Facilitator) și apare un scurt ecran de încărcare. Dacă nu este furnizată, valoarea implicită este false. |
customer.email |
Da | Șir | E-mailul plătitorului. C2P folosește valoarea pentru a căuta profilul plătitorului în sistemul SRC (Secure Remote Commerce). Căutarea e-mailului este inițiată numai dacă dispozitivul nu este recunoscut. Dacă dispozitivul este recunoscut, acest câmp este ignorat. Includeți pe site-ul dvs. informația că e-mailul plătitorului este folosit în scopul căutării, cu excepția cazului în care ați informat deja plătitorul că adresa de e-mail este folosită pentru a căuta profilul C2P. Puteți include o notificare prin care informați că sunteți partener cu schemele de carduri participante pentru a livra C2P pentru o validare mai rapidă și că adresa de e-mail a plătitorului este partajată în siguranță cu schemele de carduri participante pentru a verifica dacă au deja un profil C2P. |
customer.mobilePhone |
Nu | Număr de telefon | Numărul de telefon mobil sau celular al plătitorului în format ITU-T E123, de exemplu +1 607 1234 5678 Numărul constă în:
|
customer.firstName |
Nu | Șir | Prenumele plătitorului. |
customer.lastName |
Nu | Șir | Numele plătitorului. |
srcDCFCancel |
Da (doar dacă intenționați să acceptați cardurile Visa) | - | Designul actual al Visa pentru C2P își închide sesiunea C2P dacă plătitorul selectează simbolul „X” afișat în colțul din dreapta sus al componentei Visa DCF. Când acest eveniment este trimis, se recomandă să reinițializați C2P (apelați funcția configure()) pentru a asigura sesiuni deschise pentru toate schemele de carduri. |
Componentele paginii de plată
C2P oferă mai multe componente care pot fi încorporate în pagina dvs. de plată pentru a îmbunătăți interacțiunea C2P. Creați elemente div în locația din pagina dvs. de plată unde doriți să fie afișate aceste componente și identificați elementele div în secțiunea elemente a obiectului de configurare.
Tabel: Componente disponibile ale paginii de plată
| Câmp | Obligatoriu | Descriere |
|---|---|---|
cardList |
Da | ID-ul elementului DOM unde este afișată componenta Listă de carduri. |
otp |
Nu | ID-ul elementului DOM unde este afișată componenta One Time Password (OTP). Dacă nu este furnizat, OTP este afișat ca o suprafață suprapusă. |
dcf |
Da | ID-ul elementului DOM unde este afișată componenta DCF. Dacă nu este furnizat, componenta DCF este afișată ca o suprafață suprapusă. |
Funcții callback
Trebuie să definiți acțiunile care vor fi invocate în timpul interacțiunii C2P ca funcții de callback.
Callback onStateChange
Fluxul inițial este determinat după ce apelați funcția configure():
- Dacă este detectat un modul cookie C2P valid, este utilizat fluxul „Fluxul de utilizator care revine cu module cookie” și este afișată componenta listă de carduri.
- Dacă este detectat un e-mail C2P valid, este utilizat fluxul „Utilizator care revine cu e-mail” și plătitorului i se solicită o OTP înainte de afișarea componentei listă de carduri.
- Dacă nu este detectat niciun modul cookie sau e-mail valid, este utilizat fluxul „Utilizator nou”.
Callback-ul onStateChange este declanșat atunci când starea de interacțiune C2P se modifică. Îl puteți folosi pentru a determina ce componente sunt vizibile și în ce stadiu se află plătitorul în flux.
Exemplu de obiect callback onStateChange
oldState : {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email if not supplied in customer.email
},
elementState: {
cardList: {selector: 'cardListContainer', visible: true},
otp: {selector:'otpContainer', visible: false},
dcf: {selector:'dcfContainer', visible: false}
}
},
newState: {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: 'cardListContainer', visible: false},
otp: {selector:'otpContainer', visible: false},
dcf: {selector:'dcfContainer', visible: true}
}
},
diffState: {
elementState: {
dcf: {selector:'dcfContainer', visible: true}
}
}
Următorul tabel oferă exemple de gestionare a schimbărilor de stare cu diferitele fluxuri.
Tabel: Schimbări de stare
| Stare | Valoarea câmpului Stare veche | Valoarea câmpului Stare nouă | Comentarii |
|---|---|---|---|
| Încărcarea paginii (înainte de afișarea listei de carduri) după isRecognized și înainte de afișarea cardList | {} | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
- |
| după ce se face clic pe card și înainte de a redirecționa către DCF | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
- |
| după finalizarea validării | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
callback-ul onComplete returnează correlationId, scheme, digitalCardId. Treceți la pasul 6 |
Flux utilizator care revine cu cookie
| Stare | Valoarea câmpului Stare veche | Valoarea câmpului Stare nouă | Comentarii |
|---|---|---|---|
Încărcarea paginii după isRecognized() și înainte ca lista de carduri să fie afișată |
{} | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
- |
| După ce se face clic pe un card și înainte de redirecționarea către componenta DCF | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
- |
| după finalizarea validării | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
Callback-ul onComplete returnează ID-ul de corelare, schema și ID-ul cardului digital. Continuați de la pasul 6. |
| după ce este introdus OTP valid | {
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: true},
dcf: {selector:'#dcfContainer', visible: false}
}
}
} |
{
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
- |
| După ce se face clic pe un card, înainte de redirecționarea către componenta DCF | {
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
{
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
- |
| după finalizarea validării | {
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
{
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
Callback-ul onComplete returnează ID-ul de corelare, schema și ID-ul cardului digital. Continuați de la pasul 6. |
| Încărcarea paginii cu e-mail | {
} |
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrolled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
Deoarece profilul C2P al plătitorului nu este recunoscut, puteți afișa câmpuri de introducere a cardului, puteți aduna detaliile de la plătitor și puteți actualiza sesiunea. E-mailul este gol, dacă nu este furnizat în parametrii de configurare. |
Apelați funcția checkoutWithNewCard() înainte ca componenta DCF să fie afișată |
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrolled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrolled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
- |
| după finalizarea validării | {
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrollled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrollled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
Callback-ul onComplete returnează ID-ul de corelare, schema și ID-ul cardului digital. Continuați de la pasul 6. |
Callback onComplete
Funcția callback onComplete este declanșată atunci când plătitorul a încheiat interacțiunea cu componenta DCF.
Această funcție folosește două argumente:
scheme: Schemă card- correlationId: Identificator unic pentru interacțiunea C2P (pentru această schemă)
Aceste detalii trebuie folosite la pasul 6 pentru a prelua detaliile de plată pentru această interacțiune C2P.
Callback onError
Callback-ul onError returnează un obiect de eroare dacă apare o eroare în timpul interacțiunii C2P. Acesta conține două câmpuri:
{
errorCode: 'INVALID_INPUT',
errorMessage: 'session id is required'
}
Tabel: Coduri de eroare de integrare
| Cod de eroare | Mesaj de eroare | Acțiunea dvs. |
|---|---|---|
CALLBACKS_ONCOMPLETE_ERROR |
Argument lipsă: este necesar callback-ul onComplete | Includeți funcția callback onComplete în funcția configure(). |
CALLBACKS_ONERROR_ERROR |
Argument lipsă: este necesar callback-ul onError | Includeți metoda de callback onError în funcția configure(). |
MERCHANT_ID_ERROR |
Argument lipsă: ID-ul de comerciant este obligatoriu | Includeți câmpul merchant.id în funcția configure(). |
MERCHANT_NAME_ERROR |
Argument lipsă: Numele comerciantului este obligatoriu | Includeți câmpul merchant.name în funcția configure(). |
MERCHANT_URL_ERROR |
Argument lipsă: Este obligatorie adresa URL a comerciantului | Includeți câmpul merchant.url în funcția configure(). |
SESSION_ID_ERROR |
Argument lipsă: ID-ul de sesiune este obligatoriu | Includeți câmpul session.id în funcția configure(). |
MISSING_API_VERSION_ERROR |
Argument lipsă: Versiunea API este obligatorie | Includeți câmpul wsVersion în funcția configure(). |
ORDER_AMOUNT_ERROR |
Argument lipsă: Valoarea comenzii este obligatorie | Includeți câmpul order.amount în funcția configure(). |
ORDER_CURRENCY_ERROR |
Argument lipsă: Moneda comenzii este obligatorie | Includeți câmpul order.currency în funcția configure(). |
MIN_API_VERSION_ERROR |
Versiunea API ar trebui să fie mai mare sau egală cu 62 | Schimbați valoarea câmpului wsVersion la cel puțin 62; toate operațiunile trebuie efectuate folosind versiunea 62 sau o versiune ulterioară. |
CARD_LIST_ERROR |
Argument lipsă: Elements.cardList este necesar | Includeți câmpul elements.cardList care face legătura cu componenta div a listei de carduri. |
DCF_ERROR |
Argument lipsă: Elements.dcf este obligatoriu | Includeți câmpul elements.dcf care face legătura cu componenta div a listei de carduri. |
MISSING_EMAIL_ERROR |
Argument lipsă: e-mailul este obligatoriu | Includeți câmpul customer.email în funcția configure(). |
CUSTOMER_EMAIL_ERROR |
Eroare format e-mail clientului | Asigurați-vă că numai adresele de e-mail valide ale plătitorilor sunt acceptate de site-ul dvs. |
INTERACTION_LOCALE_ERROR |
Eroare format limbă de interacțiune | Furnizați o setare regională validă folosind formatul <limbă>_<țară>, cum ar fi en_US. |
INTERACTION_COUNTRY_ERROR |
Eroare format țară interacțiune | Furnizați o valoare de țară validă ISO 3166 alpha-3 în câmpul interaction.country. |
Tabel: Coduri de eroare validare
| Cod de eroare | Mesaj de eroare | Acțiune necesară |
|---|---|---|
CARD_MISSING |
ID-ul cardului digital sau obiectul cardului criptat era obligatoriu, dar lipsește. | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
CARD_ADD_FAILED |
Nu se poate adăuga cardul la executarea fluxului combinat | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
CARD_SECURITY_CODE_MISSING |
Securitatea cardului trebuie furnizată atunci când se execută fluxul combinat. | Asigurați-vă că câmpul cardSecurityCode din funcția ClickToPay.checkoutWithNewCard() conține o valoare din 3 cifre (sau 4 cifre pentru Amex). |
CARD_INVALID |
Număr de card nevalid atunci când fluxul combinat este executat. | Asigurați-vă că câmpul primaryAccountNumber din funcția ClickToPay.checkoutWithNewCard() este un card valid. |
CARD_NOT_RECOGNIZED |
Cardul specificat nu a fost recunoscut. | Asigurați-vă că câmpul primaryAccountNumber din funcția ClickToPay.checkoutWithNewCard() este un card valid. |
CARD_EXP_INVALID |
Dată de validitate card nevalidă. | Asigurați-vă că câmpurile panExpirationYear și panExpirationMonth din funcția ClickToPay.checkoutWithNewCard() sunt valide. |
MERCHANT_DATA_INVALID |
Datele comerciantului sunt nevalide | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
UNABLE_TO_CONNECT |
Imposibil de conectat/lansați DCF. | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
AUTH_INVALID |
Simbol ID centralizat nevalid. | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
Coduri de eroare C2P standard
| Cod de eroare | Mesaj de eroare | Acțiune necesară |
|---|---|---|
REQUEST_TIMEOUT |
Solicitarea a durat mai mult decât timpul permis. Acest lucru ar putea însemna că serviciul se confruntă cu un volum mare de apeluri. Ar trebui să încercați din nou mai târziu. Poate fi, de asemenea, pentru că SDK-ul nu poate comunica cu iFrame-ul său | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
SERVER_ERROR |
Aceasta indică faptul că serverul a întâlnit o situație neașteptată care l-a împiedicat să îndeplinească solicitarea. | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
INVALID_PARAMETER |
Valoarea furnizată pentru unul sau mai mulți parametri de solicitare este considerată nevalidă. Această eroare este generată și atunci când lipsește un câmp obligatoriu. Notă: Ori de câte ori este posibil, ar trebui să oferiți validarea clientului pentru a evita o tranzacție bidirecțională inutilă cu serverul. Constrângerile simple de validare sunt documentate ca parte a specificației API. | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
INVALID_REQUEST |
Serverul nu a putut înțelege solicitarea. De obicei, aceasta înseamnă că un câmp de date trebuie să fie într-un anumit format, dar nu este. De exemplu, decodarea în base64 poate să fi eșuat. Câmpul de mesaj poate oferi clarificări suplimentare cu privire la ce parte/câmp al solicitării este considerat incorect. | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
AUTH_ERROR |
Serverul înțelege solicitarea, dar nu poate efectua autentificarea. | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
NOT_FOUND |
Resursa/entitatea comercială solicitată nu există. Resursa ar putea fi, de asemenea, ascunsă din motive de securitate. | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
TERMS_AND_CONDITIONS_NOT_ACCEPTED |
Termenii și condițiile nu sunt acceptate. | Reveniți la fluxul de validare pentru oaspeți. |
IS_CONFIGURED_ERROR |
configure() nu s-a finalizat. Configurația trebuie inițializată mai întâi. | Asigurați-vă că integrarea a apelat funcția configure(). Asigurați-vă că lăsați suficient timp pentru ca funcția să se finalizeze înainte de a face vizibile componentele C2P. |
SRCI_ID_MISSING |
Lipsește identificatorul pentru SRC Initiator. | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
DPA_ID_MISSING |
Lipsește identificatorul pentru DPA | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
SRCI_TXID_MISSING |
Lipsește identificatorul tranzacției SRC Initiator. | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
DPA_TXOPT_MISSING |
Lipsește structura DPA Transaction Options. | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
INVALID_STATE |
Contul există, dar nu este într-o stare „activă” pentru acest program. | Reveniți la fluxul de validare pentru oaspeți. |
CONSUMER_ID_MISSING |
Identitatea consumatorului era obligatorie, dar nu a fost furnizată. | Reveniți la fluxul de validare pentru oaspeți. |
FRAUD |
Contul de utilizator a fost blocat sau dezactivat. | Reveniți la fluxul de validare pentru oaspeți. |
ID_FORMAT_UNSUPPORTED |
ID de sesiune nevalid | C2P nu este disponibil, reveniți la fluxul de validare pentru oaspeți. |
Întârzierea OTP pentru utilizatorii care revin recunoscuți prin e-mail (opțional)
Dacă plătitorul este recunoscut de C2P pe baza e-mailului său, comportamentul implicit este să arate automat OTP-ul furnizat de C2P.
Dacă, din orice motiv, doriți să inițiați interacțiunea C2P, dar suprimați OTP-ul furnizat de C2P până mai târziu (în timp ce afișați ecrane suplimentare plătitorului înainte de a continua), adăugați câmpul interaction.suppressPayerInteraction în funcția ClickToPay.configure().
Dacă setați câmpul interaction.suppressPayerInteraction la true, funcția configure() setează interacțiunea C2P și verifică dacă plătitorul este recunoscut folosind e-mailul sau un modul cookie sau dacă este un utilizator nou. Cu toate acestea, funcția nu declanșează interacțiunea C2P cu plătitorul (afișează orice componente aferente).
Dacă câmpul este omis sau este setat la false, funcția configure() setează interacțiunea C2P, verifică dacă plătitorul este recunoscut folosind e-mailul sau un cookie sau este un utilizator nou, și de asemenea declanșează imediat interacțiunea C2P cu plătitorul.
Dacă câmpul interaction.suppressPayerInteraction este setat la true, trebuie să efectuați următoarele acțiuni în funcție de starea de recunoaștere a plătitorului. Dacă plătitorul este:
- Recunoscut pe baza e-mailului lor (
emailEnrolled = trueșiemailVerified = false), aplicația comerciantului poate aplica pași suplimentari în fluxul lor înainte de a iniția verificarea OTP a C2P. Ulterior, trebuie să apelați funcțiaClickToPay.initiatePayerInteraction()pentru a afișa OTP plătitorului. - Dacă nu este recunoscut pe baza adresei de e-mail (este un utilizator nou sau este recunoscut dintr-un cookie), aplicația comerciantului trebuie să apeleze imediat funcția
initiatePayerInteraction().
Pasul 4: Actualizați modificările adresei de e-mail
Dacă plătitorul își poate schimba adresa de e-mail pe aceeași pagină care arată componentele C2P, orice modificare adusă adresei de e-mail a plătitorului trebuie să fie trimisă în SDK-ul C2P. De fiecare dată când plătitorul își actualizează adresa de e-mail, apelați funcția ClickToPay.lookupCustomer(email) pentru a actualiza SDK-ul C2P. E-mailul plătitorului este folosit pentru a căuta dacă acest plătitor are un profil C2P existent asociat cu adresa sa de e-mail.
Dacă colectați adresa de e-mail de la plătitor pe site-ul dvs., informați plătitorul că e-mailul său este folosit pentru a căuta profilul C2P. Puteți include un tooltip lângă caseta de introducere a e-mailului care să informeze plătitorul că sunteți partener cu schemele de carduri participante pentru a livra C2P pentru o validare mai rapidă și că e-mailul este partajat în siguranță cu schemele de carduri participante pentru a verifica dacă plătitorul are deja un profil C2P.
Dacă adresa de e-mail actualizată este:
-
- Conectat la un profil C2P existent:
- Callback-ul
onStateChangeeste declanșat cunewState.payerState.emailEnrolled = true. - Formularul de introducere OTP este afișat de SDK-ul JavaScript C2P.
- Callback-ul
- Neconectat la un profil C2P existent, callback-ul
onStateChangeeste declanșat cunewState.payerState.emailEnrolled = false.
Pasul 5: Implementați validarea
Dacă plătitorul decide să finalizeze cumpărătura folosind un card existent din profilul său C2P, apelați funcția ClickToPay.checkoutWithExistingCard() după ce plătitorul selectează cardul din lista de carduri. Funcția duce plătitorul la ecranul de confirmare a cardului din componenta DCF.
Dacă plătitorul decide să înscrie un nou card în profilul său C2P sau nu are un profil:
- Afișați formularul de introducere a cardului ca câmpuri Hosted Session, astfel încât plătitorul să își poată introduce detaliile de plată și să facă clic pe Plătește. Trebuie să afișați câmpurile pentru următoarele:
- Număr card
- Cod de securitate
- Luna și anul expirării
- Numele de pe card
- Preluați schemă card de la Hosted Session folosind callback-ul
PaymentSession.onCardTypeChange, care este declanșat atunci când plătitorul completează numărul de card în câmpul găzduit. - Apelați funcția
ClickToPay.isEnrollmentAvailableForScheme()folosind schema.
Funcția verifică schema de card furnizată cupaymentTypes.card.walletProviders[n].secureRemoteCommerce.scheme[n].nameîn răspunsul operațiunii PAYMENT OPTIONS INQUIRY pentru a determina dacă sunteți activat pentru schemă.
Dacă funcția returneazăfalse, părăsiți acest flux și utilizați fluxul de validare pentru oaspeți pentru a procesa cardul în mod normal, fără C2P. - Afișați și obțineți consimțământul:
- Dacă vă aflați în SUA, includeți informații conform cărora, dacă plătitorul alege să continue, veți partaja detaliile cardului plătitorului, adresa de facturare și e-mailul cu schemele de carduri participante, pentru a permite înscrierea plătitorului în C2P pentru validări mai rapide.
- Dacă vă aflați în afara SUA, afișați:
- Casetă de consimțământ nebifată.
- Text de consimțământ în care plătitorul este de acord să partajeze detaliile cardului, adresa de facturare și e-mailul cu schemele de card participante, pentru a permite înscrierea plătitorului în C2P pentru validări mai rapide.
- Când plătitorul face clic pe butonul Plătește de pe pagina dvs. de plată pentru a trece la următoarea etapă:
- Dacă vă aflați în afara SUA și caseta de consimțământ nu este bifată, plătitorul nu și-a dat consimțământul pentru a partaja date cu C2P. Urmați fluxul de validare al oaspeților și procesați cardul în mod normal, fără C2P.
- Dacă vă aflați în SUA sau în afara SUA și utilizatorul a bifat caseta de consimțământ, actualizați sesiunea utilizând funcția
PaymentSession.updateSessionFromForm().
De asemenea, puteți actualiza sesiunea cu o adresăbillingopțională folosind obiectul de facturare într-o solicitare UPDATE SESSION. Dacă introduceți detaliile de facturare ale plătitorului în sesiunea de plată, plătitorul nu trebuie să le tasteze din nou în timpul înscrierii C2P.
- După actualizarea sesiunii, apelați funcția
ClickToPay.checkoutWithNewCard(), care duce plătitorul la ecranul de înregistrare a cardului din componenta DCF:
- Dacă funcția eșuează, se apelează callback-ul
onError. Luați măsurile necesare pentru a rezolva eroarea. - Dacă funcția reușește, plătitorul este redirecționat către componenta DCF.
- Dacă funcția eșuează, se apelează callback-ul
- Plătitorul interacționează cu componenta DCF pentru a facilita înscrierea. Odată apelat callback-ul
onComplete, interacțiunea C2P este completă și puteți continua cu pasul 6 pentru a actualiza sesiunea cu detalii C2P.
Pasul 6: Actualizați sesiunea cu detaliile de plată Click to Pay
După ce plătitorul dvs. a finalizat cu succes interacțiunea C2P, trebuie să solicitați gateway-ului să recupereze detaliile de plată pentru interacțiunea C2P și să le stocați în sesiune.
Trimiteți o solicitare de API UPDATE SESSION FROM WALLET pe partea serverului cu:
- ID-ul sesiunii în adresa URL a solicitării.
- ID-ul de corelare și schema, așa cum sunt returnate în callback-ul
onComplete.
| Exemplu de solicitare UPDATE SESSION FROM WALLET |
|---|
URL: "https://egenius.unicredit.ro/form/version/<version>/merchant/<merchant_ID>/session/<session_ID>
HTTP Method POST
{
"apiOperation":"UPDATE_SESSION_FROM_WALLET",
"order":{
"walletProvider":"SECURE_REMOTE_COMMERCE"
},
"wallet":{
"secureRemoteCommerce":{
"srcCorrelationId":"<correlationId_provided_in_payloadCallback>,
"scheme":"<scheme_provided_in_payloadCallback>"
}
}
}
|
Dacă sesiunea este actualizată cu succes cu detaliile de plată din interacțiunea C2P, afișați un ecran de confirmare a plății pentru a confirma că toate detaliile sunt corecte înainte ca plătitorul să se angajeze să efectueze plata. Dacă sesiunea nu a fost actualizată cu succes, cereți plătitorului să selecteze o altă opțiune de validare.
Pasul 7: Efectuați autentificare 3D Secure (opțional)
Dacă doriți să autentificați plătitorul, efectuați Autentificarea 3D Secure folosind sesiunea. Pentru instrucțiuni detaliate, consultați 3DS cu API-ul 3DS JavaScript.
Pasul 8: Efectuați operațiunea de plată
Din cauza unei limitări a funcționalității DCF a Visa, dacă plătitorul alege să revină la pagina inițială de introducere/selectare a cardului pentru a utiliza un alt card pentru plată după ce a finalizat porțiunea DCF a fluxului, trebuie să reinițializați SDK-ul. Abordarea recomandată este să apelați din nou funcția configure().
După ce plătitorul se angajează să efectueze plata (și autentificarea 3D Secure reușește, dacă este efectuată), utilizați sesiunea pentru a trimite plata pentru procesare de pe serverul dvs. De exemplu, puteți trimite o solicitare AUTHORIZE.
Detaliile de plată stocate în sesiunea interacțiunii C2P sunt utilizate pentru procesarea plății. Puteți utiliza aceeași sesiune pentru o serie de operațiuni API. Pentru mai multe informații despre efectuarea solicitărilor de plată în cadrul unei sesiuni, consultați Noțiuni de bază privind sesiunile.
Pentru fluxurile de validare pentru oaspeți, utilizați implementarea Hosted Session de bază pentru a obține detaliile cardului din câmpurile găzduite și pentru a le adăuga la sesiune înainte de a trimite operațiunea de plată.
| Exemplu de solicitare AUTHORIZE |
|---|
URL: "https://egenius.unicredit.ro/form/version/{version}//merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID>
HTTP Method PUT
{
"apiOperation":"AUTHORIZE",
"session": {
"id": "<session_ID>"
}
}
|
Exemplu HTML pentru integrare
Această secțiune descrie o integrare simplă pentru a colecta detaliile cardului de credit al plătitorului prin intermediul Hosted Session și a configura C2P.
Hosted SessionExemplu de integrare
Exemplu
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://egenius.unicredit.ro/form/version/<Version>/merchant/<Merchant ID>/session.js"></script>
<!-- INCLUDE CLICK-TO-PAY.MIN.JS JAVASCRIPT LIBRARY -->
<script type="text/javascript" src="https://egenius.unicredit.ro/form/static/click-to-pay/click-to-pay.min.js"></script>
<!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE -->
<style id="antiClickjack">body{display:none !important;}</style>
</head>
<body>
<!-- CREATE THE HTML FOR THE PAYMENT PAGE -->
<div>Please enter your payment details:</div>
<h3>Credit Card</h3>
<div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="1" readonly></div>
<div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two-digit expiry month" value="" tabindex="2" readonly></div>
<div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two-digit expiry year" value="" tabindex="3" readonly></div>
<div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three-digit CCV security code" value="" tabindex="4" readonly></div>
<div>Cardholder Name:<input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="5" readonly></div>
<div><button id="payButton" onclick="pay('card');">Pay Now</button></div>
<!-- CREATE THE HTML FOR THE CLICK-TO-PAY INTERACTION -->
<div>C2P Fields Below------</div>
Email: <input id="payerEmail" onblur="updateEmail();" /><br/>
<div id="cardListContainer" ></div><br/>
<div id="otpContainer"></div><br/>
<div id="cardFacilitator" ></div><br/>
<div id="coid" ></div><br/>
<!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING -->
<script type="text/javascript">
if (self === top) {
var antiClickjack = document.getElementById("antiClickjack");
antiClickjack.parentNode.removeChild(antiClickjack);
} else {
top.location = self.location;
}
PaymentSession.configure({
session: "<your_session_ID>",
fields: {
// ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD
card: {
number: "#card-number",
securityCode: "#security-code",
expiryMonth: "#expiry-month",
expiryYear: "#expiry-year",
nameOnCard: "#cardholder-name"
}
},
//SPECIFY YOUR MITIGATION OPTION HERE
frameEmbeddingMitigation: ["javascript"],
callbacks: {
initialized: function(response) {
console.log('initialized: ' + response)
if(response.status === 'ok') {
//configure C2P
configure()
}
},
formSessionUpdate: function(response) {
// HANDLE RESPONSE FOR UPDATE SESSION
if (response.status) {
if ("ok" == response.status) {
console.log("Session updated with data: " + response.session.id);
//CHECK IF SECURITY CODE WAS PROVIDED BY THE USER
if (response.sourceOfFunds.provided.card.securityCode) {
console.log("Security code was provided.");
}
//CHECK IF THE USER ENTERED A MASTERCARD CREDIT CARD
if (response.sourceOfFunds.provided.card.scheme == 'MASTERCARD') {
console.log("The user entered a Mastercard credit card.")
}
ClickToPay.isEnrollmentAvailableForScheme(response.sourceOfFunds.provided.card.scheme, function (canEnroll) {
console.log('Card can be enrolled', canEnroll)
if(canEnroll) {
ClickToPay.checkoutWithNewCard();
}
});
} else if ("fields_in_error" == response.status) {
console.log("Session update failed with field errors.");
if (response.errors.cardNumber) {
console.log("Card number invalid or missing.");
}
if (response.errors.expiryYear) {
console.log("Expiry year invalid or missing.");
}
if (response.errors.expiryMonth) {
console.log("Expiry month invalid or missing.");
}
if (response.errors.securityCode) {
console.log("Security code invalid.");
}
} else if ("request_timeout" == response.status) {
console.log("Session update failed with request timeout: " + response.errors.message);
} else if ("system_error" == response.status) {
console.log("Session update failed with system error: " + response.errors.message);
}
} else {
console.log("Session update failed: " + response);
}
}
},
interaction: {
displayControl: {
formatCard: "EMBOSSED",
invalidFieldCharacters: "REJECT"
}
}
});
function pay() {
// UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
PaymentSession.updateSessionFromForm('card');
}
</script>
<script type="text/javascript">
var payloadCallback = function (correlationId, scheme) {
console.log('Payload callback complete with correlation id %s and scheme %s', correlationId, scheme);
};
var errorCallback = function (error) {
console.log('Error callback triggered with error ' + error);
console.log(error);
};
var cancelCallback = function () {
console.log('Cancel callback triggered');
};
function configure() {
ClickToPay.configure({
merchant: {
id: "<your_gateway_merchant_ID>",
name: "<your_gateway_name>",
url: "<your_web_site_URL>"
},
session: {
id: "<your_session_ID>",
wsVersion: <api_version>
},
order: {
amount: <amount>,
currency: "<currency>"
},
interaction: {
//BILLING PREFERENCE WITH ONE OF THE FOLLOWING VALUES: NONE, FULL, POSTAL_COUNTRY
billingPreference: "FULL",
collectShippingAddress: true,
locale: "<locale>",
country: "<country code>"
},
customer: {
email: "<payers_email_address>"//OPTIONAL
},
elements: {
cardList: "cardListContainer",
otp: "otpContainer", // OPTIONAL
dcf: "cardFacilitator"
},
callbacks: {
onComplete: function(correlationId, scheme) {
console.log("onComplete fired");
console.log("Correlation ID: " + correlationId);
console.log("Scheme: " + scheme);
document.getElementById("coid").innerHTML = 'Correlation ID: ' + correlationId + ', Scheme: ' + scheme
},
onStateChange: function(changeInfo) {
console.log("onStateChange fired");
console.log(changeInfo);
},
onError: function(errInfo) {
console.log("onError fired");
console.log(errInfo);
}
}
});
}
function updateEmail() {
ClickToPay.lookupCustomer(document.getElementById("payerEmail").value);
}
</script>
</body>
</html>