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 preliminareCopied to Clipboard

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 gatewayCopied to Clipboard

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.

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.

{
  "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://paymentgateway.commbank.com.au/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.

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 eroareCopied to Clipboard

Apelarea GatewayPaypal.configure() poate returna următoarele răspunsuri de eroare.

Confirmarea plățiiCopied to Clipboard

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

1. Trimiteți solicitarea Initiate Browser Payment către gateway, folosind browserPayment.paypal.paymentconfirmation = CONFIRM_AT_PROVIDER.

   Se afișează formularul de plată PayPal.

2. Plătitorul se conectează la formularul de plată PayPal, selectează instrumentul de plată și apoi face clic pe Plătiți acum.
3. Trimiteți solicitarea Confirm Browser Payment pentru a invoca solicitarea Execute Payment de la PayPal.
4. Dacă instrumentul este respins, PayPal trimite răspunsul INSTRUMENT_DECLINED la solicitarea Execute Payment.

   Un plătitor are la dispoziție, în total, trei încercări pentru a face plata.

5. 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țieiCopied to Clipboard

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

browserPayment.paypal.paymentConfirmation este CONFIRM_AT_MERCHANT

Testarea integrăriiCopied to Clipboard

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.