- Ghid de integrare
- Caracteristici acceptate (Metode de plată)
- Implementarea unei integrări pentru plată prin browser
- PayPal
- Integrare gateway în PayPal JS SDK
Integrare gateway în PayPal JS SDK
Acest ghid descrie cum să adăugați butonul inteligent PayPal la pagina de plată prin integrarea în JavaScript SDK din PayPal furnizat de gateway.
Cerințe preliminare
Pentru a oferi butonul inteligent PayPal ca opțiune de validare pentru plătitorii dvs. folosind PayPal JavaScript SDK din gateway:
- Asigurați-vă your payment service provider a activat PayPal în profilul dvs. de comerciant.
- Din meniul Admin din Merchant Administration, faceți clic pe configurația PayPal și urmați instrucțiunile de înscriere în PayPal și activați PayPal pentru profilul dvs. de comerciant. Trebuie să dețineți privilegiile necesare pentru a actualiza configurația PayPal.
Adăugarea butonului inteligent folosind PayPal JavaScript SDK din gateway
Urmați pașii de mai jos pentru a realiza propria integrare în PayPal JavaScript SDK din gateway
Pasul 1: Creați o sesiune
PayPal JavaScript SDK din gateway utilizează autentificarea pe baza sesiunii. Creați o sesiune pentru a actualiza câmpurile de solicitare și valorile pe care doriți să le stocați.
Pentru a crea o sesiune, trimiteți solicitarea Create Session din aplicația de pe serverul dvs. Răspunsul returnează un ID de sesiune pe care trebuie să îl utilizați la pașii ulteriori pentru a face referire la această sesiune.
| URL | https://egenius.unicredit.ro/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session |
| Metoda HTTP | POST |
Pasul 2: Actualizați sesiunea cu detaliile pentru comandă, tranzacție și plata prin browser
Actualizați sesiunea cel puțin cu suma și moneda comenzii, trimițând solicitarea Update Session din aplicația de pe serverul dvs.
Actualizați sesiunea cel puțin cu ID-ul de comandă, ID-ul de tranzacție, valoarea comenzii, moneda și detaliile de plată prin browser (confirmarea plății), trimițând o solicitare Update Session din aplicația dvs. de pe server.
browserPayment.returnUrl este opțională deoarece nu este necesară pentru a reda interacțiunea cu butonul inteligent PayPal pentru a funcționa.| URL | https://egenius.unicredit.ro/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session>/<your_session_ID> |
| Metoda HTTP | PUT |
{
"apiOperation": "UPDATE_SESSION",
"browserPayment": {
"operation": "PAY",
"paypal": {
"paymentConfirmation": "CONFIRM_AT_PROVIDER"
}
},
"order": {
"amount": "679.99",
"currency": "USD"
},
"sourceOfFunds": {
"type": "PAYPAL"
}
}
Pasul 3: Includeți JS SDK PayPal de pe gateway în pagina dvs. de plată
Includeți PayPal JavaScript SDK din gateway (gateway-paypal.js) în pagina dvs. de plată adăugând un element script în elementul head. Această acțiune plasează un obiect GatewayPaypal în spațiul de nume al ferestrei.
<script type="text/javascript" src="https://egenius.unicredit.ro/static/gateway-paypal/1.2.0/gateway-paypal.min.js"></script>
Pasul 4: Configurarea interacțiunii PayPal cu gateway-ul
Atunci când încărcați pagina de plată, inițiați interacțiunea cu PayPal invocând GatewayPaypal.configure (config, errorCallback, completeCallback, cancelCallback). Acest lucru va redirecționa pagina de plată către configure.html a metodei PayPal din gateway.
function errorCallback(error) {
};
function completeCallback(response) {
};
function cancelCallback(response) {
};
var config = {
merchantId: '<your_gateway_merchant_ID>', // required
orderId: '<order_ID>',//required and must match the value provided in Step 2
transactionId: '<transaction id>',// required and must match the value provided in Step 2
sessionId: '<your_session_ID>',// required
currency: '<order_currency>', // required
paymentConfirmation: '<confirmation_of_payment>', // optional, must be one of CONFIRM_AT_PROVIDER (if you want the payer to commit to the payment on the PayPal website) or CONFIRM_AT_MERCHANT (if you want the payer to commit to the payment on your website). If not provided, the value is defaulted to "CONFIRM_AT_PROVIDER".
operation: '<type_of_transaction>', // required, must be one of AUTHORIZE (transaction created in the gateway is an AUTHORIZATION transaction) or PAY (transaction created in the gateway is a PAYMENT transaction). For a successful Authorization transaction, submit a CAPTURE request to move the funds from the payer's account to your account.
apiVersion: '',// optional, Must be version 60 or above. If not provided, the value is defaulted to 60.
buttonElement: '',// required
style: {// Style options for customizing the PayPal Smart Button.
color: '<color_of_the_button>', // optional, must be one of "gold" (Recommended by PayPal), "blue", "silver", "white", "black"
shape: '<shape_of_the_button>', // optional, must be one of "rect", "pill". If not provided, the value is defaulted to "rect".
label: '<label_on_the_button>', // optional, must be one of "paypal", "checkout", "buynow", "pay". If not provided, the value is defaulted to "paypal".
tagline: '<tagline_to_be_displayed>', // optional, must be one of "true", "false". If not provided, the value is defaulted to "true".
size: '<size_of_the_button>' // optional. If not provided, the value is defaulted to the size of its container element. To customize the button width, alter the width of the container element. To customize the button height, set the height option to a value from 25 to 55.
}
};
GatewayPaypal.configure(config, errorCallback, completeCallback, cancelCallback);
merchantId
merchantId este necesar astfel încât gateway-ul să poată determina în mod corect opțiunile dvs. de plată.
apiVersion
SDK apiVersion trebuie să corespundă versiunii utilizate de dvs. la trimiterea solicitării Create Session. De exemplu, în timpul creării unei sesiuni, dacă utilizați apiVersion 61, atunci asigurați-vă că utilizați aceeași apiVersion pentru toate celelalte configurații asociate cu aceasta. Dacă există o nepotrivire între apiVersion, operațiunea va eșua.
apiVersion din config() este 61. Dacă nu furnizați valoarea pentru apiVersion, va fi luată în considerare valoarea implicită.buttonElement
Determină poziția butonului pe pagină. Este un identificator al elementului DOM unde este redat butonul.
paymentConfirmation
Indică unde în fluxul de validare doriți ca plătitorul să se angajeze la plată, poate fi pe site-ul dvs. web sau în PayPal.
Răspunsuri de eroare
Apelarea GatewayPaypal.configure() poate returna următoarele răspunsuri de eroare.
| response.cause | resp.explanation | Acțiune necesară |
|---|---|---|
| Eroare | Argument lipsă: Merchant ID, Hosted Session ID, Payment Confirmation, Button Element și trei funcții de callback sunt toate argumente necesare pentru metoda configure(). | Reparați integrarea. Furnizați toate câmpurile de solicitare obligatorii. |
| Eroare |
|
Remediați integrarea furnizând funcții corecte. |
| Eroare | Versiunea API trebuie să fie <MIN_VERSION> sau mai recentă. | Reparați integrarea. Setați apiVersion la 60 sau la o versiune ulterioară. |
Confirmarea plății
Atât în procesul Validare cu PayPal, cât și în cel de Plată cu PayPal, puteți alege să afișați butonul Plătiți acum sau butonul Continuare pe site-ul web PayPal.
Confirmarea plății în PayPal
Prin trimiterea CONFIRM_AT_PROVIDER, butonul Plătiți acum este afișat în fereastra modală PayPal. Butonul Plătiți acum permite plătitorului să confirme plata în fereastra modală PayPal. Această opțiune vă permite să oferiți plătitorului o experiență de validare mai rapidă, deoarece plătitorul finalizează plata din PayPal.
În cazul în care plătitorul se angajează la plată pe site-ul PayPal, puteți trimite o solicitare Retrieve Transaction sau Retrieve Order către gateway pentru a verifica rezultatul tranzacției. Puteți afișa apoi pagina Plată finalizată cu cele mai noi detalii.
Respingere recuperare
Respingerea recuperării este acceptată numai dacă se utilizează PayPal. În timpul procesului de tranzacție, dacă instrumentul este respins, plătitorul mai are la dispoziție două încercări de a efectua plata. Pentru toate cele trei încercări, un plătitor poate utiliza același instrument sau orice alt instrument înregistrat la PayPal pentru a efectua plata. Dacă instrumentul este unul nou, un plătitor trebuie să îl înregistreze la PayPal înainte de a continua cu plata. Un plătitor are la dispoziție, în total, trei încercări pentru a face plata. Dacă instrumentul este respins și după a treia încercare, your payment service provider va trimite răspunsul TRANSACTION_REFUSED sau INSTRUMENT_DECLINED. Apoi, plătitorul nu va putea continua procesul tranzacției.
Succesiunea evenimentelor în timpul respingerii recuperării
- Trimiteți solicitarea Initiate Browser Payment către gateway, folosind browserPayment.paypal.paymentconfirmation = CONFIRM_AT_PROVIDER.
Se afișează formularul de plată PayPal.
- Plătitorul se conectează la formularul de plată PayPal, selectează instrumentul de plată și apoi face clic pe Plătiți acum.
- Trimiteți solicitarea Confirm Browser Payment pentru a invoca solicitarea Execute Payment de la PayPal.
- Dacă instrumentul este respins, PayPal trimite răspunsul
INSTRUMENT_DECLINEDla solicitarea Execute Payment.Un plătitor are la dispoziție, în total, trei încercări pentru a face plata.
- După ce handlerul de evenimente onApprove primește răspunsul INSTRUMENT_DECLINED, apelați funcția actions.restart() pentru a permite plătitorului să aleagă alt instrument.
const restartPaymentOnInstrumentDeclined = (resp, actions) => {
if (isInstrumentDeclined(resp)) {
return actions.restart();
} else {
gatewaySuccessCallbackBP(resp);
}
}
{
"browserPayment": {
"interaction": {
"status": "INITIATED",
"timeInitiated": "2021-07-15T07:10:16.176Z"
},
"operation": "PAY",
"paypal": {
"displayShippingAddress": true,
"interactionId": "EC-9SH774983H4356451",
"overrideShippingAddress": true,
"paymentConfirmation": "CONFIRM_AT_PROVIDER"
}
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "PP_POI_1",
"order": {
"amount": 931,
"chargeback": {
"amount": 0,
"currency": "USD"
},
"creationTime": "2021-07-15T07:10:16.152Z",
"currency": "USD",
"id": "vcc-206",
"item": [
{
"brand": "MC",
"category": "NA",
"detail": {
"unitDiscountRate": 0
},
"name": "name",
"quantity": 1,
"sku": "sku",
"unitDiscountAmount": 0,
"unitPrice": 931
}
],
"itemAmount": 931,
"lastUpdatedTime": "2021-07-15T07:12:19.571Z",
"merchantAmount": 931,
"merchantCurrency": "USD",
"reference": "my order",
"status": "INITIATED",
"taxAmount": 0,
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"acquirerCode": "INSTRUMENT_DECLINED",
"acquirerMessage": "",
"debugInformation": "INSTRUMENT_DECLINED, The instrument presented was either declined by the processor or bank, or it can't be used for this payment., e5a837ee6834",
"gatewayCode": "SUBMITTED"
},
"result": "SUCCESS",
"shipping": {
"address": {
"city": "Los Angeles",
"company": "Google",
"country": "USA",
"postcodeZip": "90001",
"stateProvince": "CA",
"street": "2nd Main",
"street2": "lane 2"
},
"contact": {
"email": "ramakanth@gmail.com",
"firstName": "Ramakanth",
"lastName": "Kulkarni",
"mobilePhone": "9999999999",
"phone": "9999999999"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"accountEmail": "CCREJECT-REFUSED@paypal.com",
"accountHolder": "Paul Levetsky",
"payerId": "LM9AM5Y34N3X8"
}
},
"type": "PAYPAL"
},
"timeOfLastUpdate": "2021-07-15T07:12:19.571Z",
"timeOfRecord": "2021-07-15T07:10:16.171Z",
"transaction": {
"acquirer": {
"date": "15 Jul 2021",
"id": "PAYPAL",
"merchantId": "NDXE9MFKNPCUA",
"time": "07:12:19"
},
"amount": 931,
"currency": "USD",
"id": "1",
"source": "INTERNET",
"stan": "0",
"type": "PAYMENT",
"update": [
{
"gatewayCode": "SUBMITTED",
"time": "2021-07-15T07:10:17.280Z"
}
]
},
"version": "62"
}
{
"browserPayment": {
"interaction": {
"status": "COMPLETED",
"timeCompleted": "2021-07-20T09:17:27.128Z",
"timeInitiated": "2021-07-20T09:15:56.313Z"
},
"operation": "PAY",
"paypal": {
"displayShippingAddress": true,
"interactionId": "EC-74C02380KE247305K",
"overrideShippingAddress": true,
"paymentConfirmation": "CONFIRM_AT_PROVIDER"
}
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "PP_POI_1",
"order": {
"amount": 1.28,
"chargeback": {
"amount": 0,
"currency": "USD"
},
"creationTime": "2021-07-20T09:15:56.278Z",
"currency": "USD",
"description": "Ordered goods",
"id": "testsdkhco33",
"item": [
{
"brand": "MC",
"category": "NA",
"name": "name",
"quantity": 1,
"sku": "sku",
"unitPrice": 1.28
}
],
"itemAmount": 1.28,
"lastUpdatedTime": "2021-07-20T09:17:27.136Z",
"merchantAmount": 1.28,
"merchantCurrency": "USD",
"reference": "my order",
"status": "FAILED",
"taxAmount": 0,
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"acquirerCode": "TRANSACTION_REFUSED",
"acquirerMessage": "",
"debugInformation": "TRANSACTION_REFUSED, The request was refused, cae635b964420",
"gatewayCode": "DECLINED"
},
"result": "FAILURE",
"shipping": {
"address": {
"city": "Los Angeles",
"country": "USA",
"postcodeZip": "90001",
"stateProvince": "CA",
"street": "2nd Main",
"street2": "lane 2"
},
"contact": {
"firstName": "Ramakanth",
"lastName": "Kulkarni"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"accountEmail": "CCREJECT-REFUSED@paypal.com",
"accountHolder": "Paul Levetsky",
"payerId": "LM9AM5Y34N3X8"
}
},
"type": "PAYPAL"
},
"timeOfLastUpdate": "2021-07-20T09:17:27.136Z",
"timeOfRecord": "2021-07-20T09:15:56.308Z",
"transaction": {
"acquirer": {
"date": "20 Jul 2021",
"id": "PAYPAL",
"merchantId": "NDXE9MFKNPCUA",
"time": "09:17:27"
},
"amount": 1.28,
"currency": "USD",
"id": "1",
"source": "INTERNET",
"stan": "0",
"type": "PAYMENT",
"update": [
{
"gatewayCode": "SUBMITTED",
"time": "2021-07-20T09:15:57.482Z"
},
{
"gatewayCode": "DECLINED",
"time": "2021-07-20T09:17:27.128Z"
}
]
},
"version": "62"
}
Confirmarea plății pe site-ul magazinului dvs.
Prin trimiterea CONFIRM_AT_MERCHANT, butonul Continuare este afișat în fereastra modală PayPal.
Butonul Continuare permite redirecționarea plătitorului către site-ul magazinului dvs. pentru confirmarea plății după finalizarea interacțiunii cu fereastra modală PayPal. Această opțiune vă permite să modificați, dacă este necesar, comanda, înainte de a accepta plata (de exemplu, adăugând taxele de livrare și manipulare pe baza adresei returnate de la PayPal).
În cazul în care plătitorul se angajează la plată pe site-ul dvs., utilizați CONFIRM_AT_MERCHANT drept confirmare a plății, pagina de confirmare a plății va fi afișată plătitorului. Puteți trimite o solicitare Retrieve Transaction sau Retrieve Order către gateway pentru a verifica rezultatul tranzacției. După ce plătitorul decide să continue plata, trebuie să trimiteți CONFIRM_BROWSER_PAYMENT către gateway pentru a finaliza plata. Puteți afișa apoi pagina Plată finalizată cu cele mai noi detalii. Puteți utiliza această operațiune pentru a actualiza atributele plății, cum ar fi costurile de expediere, pentru a reflecta detaliile expedierii selectate de plătitor în interfața PayPal.
{
"apiOperation": "CONFIRM_BROWSER_PAYMENT",
"order": {
"amount": "779.99",
"currency": "USD",
"shippingAndHandlingAmount": "100.00"
}
}
Preluarea detaliilor tranzacției
Puteți recupera detaliile tranzacției pentru interacțiunea PayPal prin următoarele opțiuni:
- Operațiunile Retrieve Order sau Retrieve Transaction
- Căutare comenzi și tranzacții în Merchant Administration: Utilizați numărul de referință furnizat plătitorului în confirmarea plății pentru a vedea detaliile tranzacției. Numărul de referință va fi disponibil în extrasul pentru plătitor și extrasul bancar. Aceasta vă permite să validați mai departe tranzacția.
Înțelegerea stării comenzii și tranzacției
browserPayment.paypal.paymentConfirmation este CONFIRM_AT_PROVIDER
| Stare interacțiune plată prin browser | Cod de răspuns gateway de tranzacție | Stare comandă | Descriere |
|---|---|---|---|
| browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | Ați trimis tranzacția folosind operațiunea INITIATE_BROWSER_PAYMENT. |
| browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | Plătitorul a făcut clic pe butonul Plătiți acum și solicitarea CONFIRM_BROWSER_PAYMENT este trimisă. |
INSTRUMENT_DECLINED, atunci starea response.gatewayCode va fi SUBMITTED, iar starea order.status va fi INITIATED. Această stare va rămâne aceeași dacă instrumentul este respins la primele două încercări de a efectua plata. Dacă instrumentul este respins și la cea de-a treia încercare, tranzacția va fi respinsă, iar starea response.gatewayCode și order.status se va schimba la DECLINED, respectiv FAILED.browserPayment.paypal.paymentConfirmation este CONFIRM_AT_MERCHANT
| Stare interacțiune plată prin browser | Cod de răspuns gateway de tranzacție | Stare comandă | Descriere |
|---|---|---|---|
| browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | Ați trimis tranzacția folosind operațiunea INITIATE_BROWSER_PAYMENT. |
| browserPayment.interaction.status=RETURNED_TO_MERCHANT | response.gatewayCode=SUBMITTED | order.status=INITIATED | Plătitorul a făcut clic pe butonul Continuare din PayPal și operațiunea UPDATE_BROWSER_PAYMENT este trimisă. |
| browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | Ați trimis operațiunea CONFIRM_BROWSER_PAYMENT. |
Testarea integrării
După ce finalizați integrarea cu gateway-ul pentru PayPal, o puteți testa folosind mediul sandbox PayPal.
Pentru a începe testul, creați un cont în PayPal și utilizați respectivele date de autentificare în timp ce configurați profilul comerciantului la your payment service provider. Asigurați-vă că utilizați comerciantul non-TEST pentru aceste tranzacții.
- Utilizați profilul dvs. comerciant creat în mediul sandbox PayPal.
- Utilizați pașii menționați anterior pentru integrare.
- Asigurați-vă că ați configurat integrarea PayPal în Merchant Administration și că ați acordat terțului permisiunea pentru gateway pentru a tranzacționa în numele dvs.