Gateway Integration to PayPal JS SDK
This guide describes how to add PayPal Smart Button to your payment page by integrating to the PayPal JavaScript SDK provided by the gateway.
Prerequisites
To offer the PayPal Smart Button as a checkout option to your payers by using gateway's PayPal JavaScript SDK:
- Ensure your payment service provider has enabled PayPal on your merchant profile.
- From the Admin menu in Merchant Administration , click PayPal Configuration and follow the instructions to onboard to PayPal and activate PayPal for your merchant profile. You must have the required privilege to update your PayPal configuration.
Add smart button using gateway's PayPal JavaScript SDK
Follow the steps outlined below to build your integration to gateway's PayPal JavaScript SDK.
Step 1: Create a session
The gateway's PayPal JavaScript SDK uses session-based authentication. Create a session to update the request fields and values that you want to store.
To create a session, submit the Create Session request from your server-side application. The response returns a session ID that you must use in the subsequent steps to reference this session.
| URL | https://ap-gateway.mastercard.com/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session |
| HTTP Method | POST |
Step 2: Update the session with the order, transaction, and browser payment details
Update the session with the amount and currency for the order by submitting the Update Session request from your server-side application.
Update the session with at least the order ID, transaction ID, order amount, currency and the browser payment details (Payment Confirmation) by submitting the Update Session request from your server-side application.
browserPayment.returnUrl is optional as it is not required to render the PayPal Smart Button interaction to work.| URL | https://ap-gateway.mastercard.com/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session>/<your_session_ID> |
| HTTP Method | PUT |
{
"apiOperation": "UPDATE_SESSION",
"browserPayment": {
"operation": "PAY",
"paypal": {
"paymentConfirmation": "CONFIRM_AT_PROVIDER"
}
},
"order": {
"amount": "679.99",
"currency": "USD"
},
"sourceOfFunds": {
"type": "PAYPAL"
}
}
Step 3: Include the gateway PayPal JS SDK in your payment page
Include the gateway's PayPal JavaScript SDK (gateway-paypal.js) in your payment page by adding a script element within the head element. This places the GatewayPaypal object into the window namespace.
<script type="text/javascript" src="https://ap-gateway.mastercard.com/static/gateway-paypal/1.2.0/gateway-paypal.min.js"></script>
Step 4: Configure the gateway PayPal interaction
When loading your payment page, initiate the PayPal interaction by invoking GatewayPaypal.configure (config, errorCallback, completeCallback, cancelCallback). This will redirect your payment page to configure.html of gateway PayPal method.
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
The merchantId is required so that the gateway can correctly determine your payment options.
apiVersion
The SDK apiVersion must match the version that you use while submitting the Create Session request. For example, while creating a session if you use the apiVersion 61, then ensure to use the same apiVersion for all the other configurations related to it. If there is a mismatch between the apiVersion, the operation will fail.
apiVersion on the config() is 61. If you do not provide the value
for apiVersion, the default value is considered.buttonElement
Determines the position of the button on the page. It is an identifier of the DOM element where the button gets rendered.
paymentConfirmation
Indicates where in the checkout flow you want the payer to commit to the payment, it can either be on your website or at PayPal.
Error responses
The GatewayPaypal.configure() call might return the following error responses.
| response.cause | resp.explanation | Required Action |
|---|---|---|
| Error | Missing argument: Merchant ID, Hosted Session ID, Payment Confirmation, Button Element and three callback functions are all required arguments for the configure() method. | Fix your integration. Provide all the mandatory request fields. |
| Error |
|
Fix your integration by providing correct functions. |
| Error | API version must be <MIN_VERSION> or greater. | Fix your integration. Set apiVersion to 60 or above. |
Payment confirmation
With both Checkout with PayPal and Pay with PayPal checkout flows, you can choose to display either the Pay Now button or the Continue button at PayPal.
Confirming the payment at PayPal
By submitting CONFIRM_AT_PROVIDER, Pay Now button gets displayed in the PayPal's modal. The Pay Now button allows the payer to confirm the payment on the PayPal modal. This option allows you to provide a faster checkout experience to the payer as the payer completes the payment at PayPal.
In case the payer commits to the payment on the PayPal site, you can submit Retrieve Transaction or Retrieve Order request to the gateway to verify the outcome of the transaction. You can then display the Payment Complete page with the latest details.
Decline Recovery
Decline recovery is supported only using PayPal. During the transaction process if
the instrument gets declined then the payer gets two more attempts to make the payment.
For all the three attempts, a payer can use the same or any another instrument which is registered with PayPal to
proceed with the payment. If it is a new instrument, a payer must register it with PayPal before proceeding wth the
payment. A payer gets three attempts in total to make the payment. If even after the third attempt the
instrument gets declined, your payment service provider will send the TRANSACTION_REFUSED or the
INSTRUMENT_DECLINED response. Henceforth, the payer will not be able to proceed with the transaction
process.
Sequence of Events during Decline Recovery
- Submit the Initiate Browser Payment request to the gateway with browserPayment.paypal.paymentconfirmation = CONFIRM_AT_PROVIDER.
The PayPal's payment form is displayed.
- A payer logs in to the PayPal's payment form, selects the payment instrument, and then clicks Pay Now.
- Submit the Confirm Browser Payment request to invoke the PayPal's Execute Payment request.
- If the instrument is declined, PayPal sends the
INSTRUMENT_DECLINEDresponse to the Execute Payment request.A payer gets three attempts in total to make the payment.
- After the onApprove event handler receives the INSTRUMENT_DECLINED response, call the actions.restart() function to allow a payer to choose a different 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"
}
Confirming the payment at your shop site
By submitting CONFIRM_AT_MERCHANT, the Continue button gets displayed on PayPal's modal.
The Continue button allows the payer to be redirected to your shop site to confirm the payment after completing interaction with the PayPal modal. This option allows you to change the order if necessary before accepting the payment (for example, adding shipping and handling charges based on the address returned from PayPal).
In case the payer commits to the payment on your site, that is, use CONFIRM_AT_MERCHANT as a Payment Confirmation, the payment confirmation page will be displayed to the payer. You can submit Retrieve Transaction or Retrieve Order request to the gateway to verify the outcome of the transaction. Once the payer decides to proceed with the payment, you must submit CONFIRM_BROWSER_PAYMENT to the gateway to finalize the payment. You can then display the Payment Complete page with the latest details. You can use this operation to update attributes of the payment, such as shipping costs, to reflect shipping details selected by the payer on the PayPal UI.
{
"apiOperation": "CONFIRM_BROWSER_PAYMENT",
"order": {
"amount": "779.99",
"currency": "USD",
"shippingAndHandlingAmount": "100.00"
}
}
Retrieving transaction details
You can retrieve transaction details for the PayPal interaction through the following options:
- Retrieve Order or Retrieve Transaction operations
- Order and Transaction Search in Merchant Administration: Use the reference number provided to the payer on the payment receipt to see the transaction details. The reference number will be available on the payer and your bank statement. This lets you further validate the transaction.
Understanding the order and transaction status
browserPayment.paypal.paymentConfirmation is CONFIRM_AT_PROVIDER
| Browser Payment Interaction Status | Transaction Gateway Response Code | Order Status | Description |
|---|---|---|---|
| browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | You have submitted the transaction using INITIATE_BROWSER_PAYMENT operation. |
| browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | Payer has clicked Pay Now button and CONFIRM_BROWSER_PAYMENT request is submitted. |
INSTRUMENT_DECLINED then the status of response.gatewayCode will be SUBMITTED and of order.status will be INITIATED.
This status will remain same if the instrument is declined in the first two attempts of making the payment. If the
instrument is declined in the third attempt as well, then the transaction will be declined and the status for response
.gatewayCode and order.status will change to DECLINED and FAILED respectively.browserPayment.paypal.paymentConfirmation is CONFIRM_AT_MERCHANT
| Browser Payment Interaction Status | Transaction Gateway Response Code | Order Status | Description |
|---|---|---|---|
| browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | You have submitted the transaction using INITIATE_BROWSER_PAYMENT operation. |
| browserPayment.interaction.status=RETURNED_TO_MERCHANT | response.gatewayCode=SUBMITTED | order.status=INITIATED | Payer has clicked Continue button in PayPal and UPDATE_BROWSER_PAYMENT operation is submitted |
| browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | You have submitted the CONFIRM_BROWSER_PAYMENT operation. |
Testing your integration
When you have completed your integration with the gateway for PayPal, you can test it by using the PayPal sandbox.
To begin the test, create an account with PayPal and use those credentials while setting up your merchant profile with your payment service provider. Ensure you use the non-TEST merchant for these transaction.
- Use your merchant profile created in the PayPal Sandbox.
- Use the abovementioned steps for integration.
- Ensure you have configured the PayPal integration in Merchant Administration, and have granted the third-party permission to the gateway to transact on your behalf.