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 <your_host_name>/api/rest/version/61/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 <your_host_name>/api/rest/version/61/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://<your_host_name>/static/gateway-paypal/1.0.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 60. 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.

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.

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.

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 the 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.

Copyright © 2021 MasterCard