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.

Example Request

URL	https://na.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.

Providing browserPayment.returnUrl is optional as it is not required to render the PayPal Smart Button interaction to work.

Example Request

URL	https://na.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://na.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.

Example Request

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.

By default, the 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	misconfigured errorCallback/completeCallback/cancelCallback missing errorCallback/completeCallback/cancelCallback invalid errorCallback/completeCallback/cancelCallback	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_DECLINED response 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.

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": "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"
}

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"
}

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.

Decline Recovery is not supported in CONFIRM_AT_MERCHANT (Checkout with PayPal).

Example Request

{
  "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.

In case of Decline Recovery, if you receive 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.