- Ghid de integrare
- Caracteristici acceptate (Metode de plată)
- Implementarea unei integrări pentru plată prin browser
- PayPal
- Integrare directă în PayPal JS SDK
Integrare directă în PayPal JS SDK
Acest ghid descrie cum să adăugați butonul inteligent PayPal la pagina de plată prin integrarea directă în JavaScript SDK din PayPal.
Cerințe preliminare
Pentru a oferi butonul inteligent PayPal ca opțiune de validare pentru plătitorii dvs. folosind JavaScript SDK din PayPal:
- Asigurați-vă că your payment service provider are un cont PayPal și a creat o aplicație cu acest cont PayPal. Your payment service provider trebuie să fi primit ID-ul de client de la PayPal și să îl fi stocat în profilul dvs. de comerciant în Administrator comercianți.
- 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.
Fluxul de informații
Următorii pași descriu fluxul de informații pentru o integrare directă în PayPal JS SDK:
- Plătitorul face clic pe butonul inteligent PayPal de pe pagina dvs. de plată.
- Javascript din browserul plătitorului trimite o solicitare către serverul dvs.
- Serverul dvs. execută operațiunea Initiate Browser Payment în gateway pentru a începe procesul de plată cu PayPal.
- Gateway-ul returnează ID-ul interacțiunii din PayPal către serverul dvs.
- Serverul dvs. returnează ID-ul interacțiunii către Javascript care este executat browserul plătitorului.
- Browserul plătitorului afișează apoi interfața PayPal.
- Javascript din browserul plătitorului interacționează cu serverul dvs. pentru a continua procesul de plată.
- Serverul dvs. execută operațiunea Confirm Browser Payment în gateway pentru a finaliza plata.
Adăugarea butonului inteligent folosind JavaScript SDK din PayPal
Urmați pașii de mai jos pentru a realiza propria integrare în JavaScript SDK din PayPal.
Pasul 1: Obțineți ID-ul clientului
Obțineți ID-ul de client trimițând solicitarea Payment Options Inquiry către gateway. Răspunsul returnează un ID de client pe care trebuie să îl utilizați în pașii ulteriori.
Exemplu de solicitare
https://<your_host_name>/api/rest/version/<api_version>/merchant/<your_gateway_merchantId>/paymentOptionsInquiry
Exemplu de răspuns
{
"merchant": "TESTPP_V2_MER33;",
"paymentTypes": {
"paypal": {
"currencies": [
{
"currency": "AUD"
},
],
"transactionSources": [
{
"transactionSource": "INTERNET"
}
]
"clientId": "ARLDC7ynAfGNlnJy8PuLanMRQvteg9RsfxAMLK-43amD5_urCn0Jl1APryAyWEvIm_GY1ippISEwsoza",
"accountId": "RMU2YU3VN8SUL"
}
},
"result": "SUCCESS",
"supportedPaymentOperations": [
{
"supportedPaymentOperation": "AUTHORIZE"
}
]
}
Pasul 2: Adăugarea PayPal JavaScript SDK la pagina dvs. web
Pentru a activa funcționalitatea butonului inteligent PayPal, adăugați PayPal JavaScript SDK la pagina dvs. web. Utilizați ID-ul de client pe care l-ați primit ca răspuns la Payment Options Inquiry de la pasul 1 ca valoare a parametrului de interogare id client.
Exemplu de cod HTML
<!DOCTYPE html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
</head>
<body>
<script src="https://www.paypal.com/sdk/js?client-id=PayPal_CLIENT_ID and merchant-id=PayPal_MERCHANT_ID">
</script>
</body>
Pentru mai multe detalii despre acest pas, consultați pasul 2 din ghidul PayPal pentru dezvoltatori.
Pasul 3: Redați butonul inteligent PayPal pe pagina dvs. web
Pentru a include butonul inteligent PayPal pe pagina dvs. web, adăugați codul de mai jos la pagina dvs. web. Utilizați ID-ul de client pe care l-ați primit ca răspuns la Payment Options Inquiry de la pasul 1.
Exemplu
<body>
<script src="https://www.paypal.com/sdk/js?client-id=PayPal_CLIENT_ID and merchant-id=PayPal_MERCHANT_ID">
</script>
<div id="paypal-button-container"></div>
<script>
paypal.Buttons().render('#paypal-button-container'); // This function displays Smart Payment Buttons on your web page.
</script>
</body>
Pentru mai multe detalii despre acest pas, consultați pasul 3 din ghidul PayPal pentru dezvoltatori.
Pasul 4: Configurați o tranzacție
Trebuie să setați funcția callback createOrder pentru a informa gazda dvs. să trimită solicitarea Initiate Browser Payment către gateway. Pentru a configura o tranzacție din serverul sau clientul dvs., consultați secțiunea Configurarea unei tranzacții din ghidul PayPal pentru dezvoltatori.
Succesiunea evenimentelor diferă în funcție de fluxul de validare PayPal.
- Pentru validare cu PayPal, consultați Succesiunea evenimentelor în timpul validării cu PayPal.
- Pentru plată cu PayPal, consultați Succesiunea evenimentelor în timpul plății cu PayPal.
Succesiunea evenimentelor în timpul validării cu PayPal
- Trimiteți solicitarea Initiate Browser Payment către gateway, folosind
browserPayment.paypal.paymentconfirmation = CONFIRM_AT_MERCHANTExemplu de solicitare{ "apiOperation": "INITIATE_BROWSER_PAYMENT", "browserPayment": { "operation": "PAY", "paypal": { "paymentConfirmation": "CONFIRM_AT_MERCHANT" } }, "order": { "amount": "679.99", "currency": "USD" }, "sourceOfFunds": { "type": "PAYPAL" } }Exemplu de răspuns"browserPayment.paypal.interactionId": "EC-8AT72418NV353182U" - Implementați o funcție de manipulare callback care este invocată atunci când un plătitor face clic pe butonul inteligent PayPal (afișat ca
createOrderCallbackHandlerîn exemplul de la Pasul 4). Această funcție de manipulare trebuie să interacționeze cu serverul dvs. pentru a trimite solicitarea Initiate Browser Payment către gateway. - Trimiteți solicitarea Initiate Browser Payment de pe serverul dvs., apoi returnați
browserPayment.paypal.interactionIdRăspunsul Initiate Browser Payment conține tokenul de validare expres în câmpul
browserPayment.paypal.interactionId.Exemplu de solicitarecreateOrder: function() { return fetch('/my-server/create-paypal-transaction', { method: 'post', headers: { 'content-type': 'application/json' } }).then(function(res) { return res.json(); }).then(function(data) { return data.interactionId; // Return the interactionId as provided by the gateway to your server }); } - PayPal JavaScript primește formularul de plată de la PayPal, apoi redă formularul în browserul plătitorului.
- Plătitorul se conectează la PayPal și trimite detaliile de plată către PayPal.
- Înregistrați funcția de manipulare onApprove în PayPal.
- După ce tranzacția din interfața PayPal reușește, funcția de manipulare onApprove este invocată. Acum, trimiteți solicitarea Update Browser Payment de pe serverul dvs. către gateway pentru a obține cele mai noi detalii de plată.
Funcție de manipulare approveCallback
onApprove: function (data, actions) { // CALL TO UPDATE_BROWSER_PAYMENT from your server; };Exemplu de solicitare Update Browser Payment//URL https://<your_host_name>/api/rest/version/latest/merchant/<your_merchant_id>/transaction/151109242cvbnv //Body { "apiOperation": "UPDATE_BROWSER_PAYMENT" }Exemplu de răspuns Update Browser Payment{ "device": { "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36", "ipAddress": "66.159.204.102" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "TESTMAN1234", "order": { "amount": 679.99, "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2020-09-17T09:38:41.924Z", "currency": "USD", "id": "421d49456789012345678909234527890", "lastUpdatedTime": "2020-09-17T09:40:11.894Z", "merchantAmount": 679.99, "merchantCurrency": "USD", "status": "CAPTURED", "totalAuthorizedAmount": 679.99, "totalCapturedAmount": 679.99, "totalRefundedAmount": 0 }, "response": { "acquirerCode": "Success", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "shipping": { "address": { "city": "Market City", "country": "AUS", "postcodeZip": "4322", "stateProvince": "Queensland", "street": "35 Rainbow street", "street2": "Floor 5, Apartment 34" }, "contact": { "firstName": "John", "lastName": "Smith", "phone": "0745231111" } }, "timeOfLastUpdate": "2020-09-17T09:40:11.894Z", "timeOfRecord": "2020-09-17T09:38:41.945Z", "transaction": { "acquirer": { "date": "2020-09-17", "id": "PAYPAL", "merchantId": "m.m@g.com", "time": "09:40:11", "transactionId": "SVE2APDYOXKMA7RY0" }, "amount": 679.99, "currency": "USD", "id": "151109242cvbnv", "receipt": "SVE2APDYOXKMA7RY0", "source": "INTERNET", "stan": "0", "type": "PAYMENT", "update": [ { "gatewayCode": "SUBMITTED", "time": "2020-09-17T09:38:42.054Z" }, { "gatewayCode": "APPROVED", "time": "2020-09-17T09:40:11.896Z" } ] }, "version": "59" } - Dacă se modifică suma din cauza unei modificări a costului de expediere, afișați plătitorului suma delta.
- După ce plătitorul confirmă plata, trimiteți solicitarea CONFIRM_BROWSER_PAYMENT pentru a finaliza tranzacția.
Exemplu de solicitare
{ "apiOperation": "CONFIRM_BROWSER_PAYMENT", "order": { "amount": "779.99", // amount updated as a result of updated shipping and handling charges "shippingAndHandlingAmount": "100.00" // updated shipping and handling charges ... } }
Respingerea recuperării nu este acceptată în CONFIRM_AT_MERCHANT (respectiv, Validare cu PayPal).
Succesiunea evenimentelor în timpul plății cu PayPal
- Trimiteți solicitarea Initiate Browser Payment către gateway, folosind
browserPayment.paypal.paymentconfirmation = CONFIRM_AT_PROVIDERExemplu de solicitare{ "apiOperation": "INITIATE_BROWSER_PAYMENT", "browserPayment": { "operation": "PAY", "paypal": { "paymentConfirmation": "CONFIRM_AT_PROVIDER" } }, "order": { "amount": "679.99", "currency": "USD" }, "sourceOfFunds": { "type": "PAYPAL" } }Exemplu de răspuns"browserPayment.paypal.interactionId": "EC-8AT72418NV353182U" - Implementați funcția callback
createOrderîn codul butonului inteligent PayPal. Atunci când un plătitor face clic pe butonul inteligent PayPal, acest cod va fi executat de PayPal. - Trimiteți solicitarea Initiate Browser Payment, de pe serverul dvs., apoi returnați
browserPayment.paypal.interactionIdRăspunsul Initiate Browser Payment conține câmpul
browserPayment.paypal.interactionId.ExemplucreateOrder: function() { return fetch('/my-server/create-paypal-transaction', { method: 'post', headers: { 'content-type': 'application/json' } }).then(function(res) { return res.json(); }).then(function(data) { return data.interactionId; // Return the interactionId as provided by the gateway to your server }); } - PayPal JavaScript primește formularul de plată de la PayPal, apoi redă formularul în browserul plătitorului.
- Plătitorul se conectează la PayPal și trimite detaliile de plată către PayPal.
- Înregistrați funcția de manipulare onApproveCallback în PayPal.
- După ce tranzacția din interfața PayPal reușește, funcția de manipulare
onApproveeste invocată. Acum, trimiteți solicitarea CONFIRM_BROWSER_PAYMENT de pe serverul dvs. către gateway pentru a finaliza plata.Funcție de manipulare approveCallbackonApprove: function (data, actions) { // CALL TO CONFIRM_BROWSER_PAYMENT from your server; };Exemplu de solicitare{ "apiOperation": "CONFIRM_BROWSER_PAYMENT" } - (Opțional) 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. Pentru mai multe informații, consultați Respingerea recuperării.
Trebuie să faceți
action.restart()pentru a permite DECLINE_RECOVERY.
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.
Respingerea recuperării nu este acceptată în CONFIRM_AT_MERCHANT (Validare cu PayPal).
action.restart()
const restartPaymentOnInstrumentDeclined = (resp, actions) => {
if (isInstrumentDeclined(resp)) {
return actions.restart();
} else {
gatewaySuccessCallbackBP(resp);
}
}
INSTRUMENT_DECLINED
{
"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": "johnsmith@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"
}
TRANSACTION_REFUSED
{
"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"
}
Testarea integrării
După ce finalizați integrarea cu 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 pașii menționați anterior pentru integrare.
- Asigurați-vă că trimiteți solicitarea Payment Options Inquiry pentru a primi ca răspuns ID-ul de client al your payment service provider.
- 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.