This guide provides technical instructions for integrating PayPal using BR-DGE’s API-first approach. This flow separates order creation from payment processing to provide greater control over the transaction lifecycle.

This guide make reference to scripts, functions & callbacks provided by the PayPal JavaScript SDK. The examples on this page are intended to be used to kick start your integration. For a full overview of the PayPal JavaScript SDK and it's features you should also read PayPal's documentation.

Overview

The API-first integration follows a structured sequence where orders are created via the BR-DGE REST API, customer approval is managed by the PayPal SDK, and final payment processing is completed via BR-DGE after approval.

PayPal via the BR-DGE REST API flows in the following way:

You load the PayPal SDK and inject the PayPal button into your checkout page.
Your customer clicks the PayPal button.
You create a PayPal order with a call from your backend server to the BR-DGE REST API.
BR-DGE return a PayPal order and you pass the order details to PayPal.
Your customer completes the payment directly with PayPal and you're informed of the completion.
You authorise or capture the payment with a backend API call to BR-DGE.

Prerequisites

To get started making PayPal payments via BR-DGE ensure you have the following:

A BR-DGE Server API Key.
A PayPal account configured on your retail channel.
Your PayPal Client ID configured with BR-DGE.

Load PayPal SDK

Load the PayPal SDK into your checkout page by passing the required variables. You can dynamically create a script element to include your clientId and currency.

function loadPaypalSDK(config) {
  const script = document.createElement('script');
  script.src = `https://www.paypal.com/sdk/js?client-	id=${PAYPAL_CLIENTID}&currency=${TRANSACTION_CURRENCY}`;
  script.onload = renderPaypalButton;
  document.head.appendChild(script);
}

PayPal Pay Later

To enable PayPal Pay Later functionality, include the specific components and funding flags in the SDK URL.

Components: buttons, messages.
Enable Funding: paylater.

<script src="https://www.paypal.com/sdk/js?client-	id=${PAYPAL_CLIENTID}&components=buttons,messages&enable-funding=paylater"></script>

📘
Pay Later offers are determined by the PayPal SDK based on country and buyer eligibility.

Render PayPal Button

Once the SDK is loaded, render the button to your container. You must provide the two callback functions defined above.

The below example has two additional functions: createPayPalOrder & finalisePayPalPayment. Making PayPal call functions from their callbacks is not mandatory. You can run the order creation & post approval steps directly inline with the callback functions. The PayPal SDK documentation shows examples of how you can achieve this:

function renderPaypalButton() {
  paypal.Buttons({
    createOrder: createPayPalOrder,
    onApprove: finalisePayPalPayment
  }).render('#paypal-button-container');
}

Callback Functions

PayPal require a minimum of two callback functions to be defined for use as part of the payment processing flow.

createOrder --> Informs your backend that the customer has clicked the button to initiate an order.
onApprove --> Called by PayPal after the customer completes the checkout so you can finalise the payment.

PayPal offer additional callbacks in their SDK all the available functions are available to view on the PayPal documentation site, here.

Create Order Callback

The createOrder callback is fired by PayPal when the customer has clicked the PayPal button prompting you to make a call from your backend server to the BR-DGE REST API to create a PayPal order.

You do this by making a request to POST /v1/paypal/orders passing in the required request details. Check out the API reference documentation for this endpoint for a full view of how to create a PayPal order.

Your callback should return the orderId from the BR-DGE REST API to the createOrder function.

You can check out the PayPal createOrder documentation directly, here.

On Approve Callback

The onApprove callback is fired by PayPal when the customer has completed the payment.

When this callback is fired you should inform your backend server and make a request to POST /v1/paypal/orders/{orderId}/payments endpoint passing in the orderId from the order creation step.

Check out the API reference documentation for this endpoint for a full view of how to authorise or capture a PayPal order.

❗️
If you do not call the BR-DGE REST API to authorise or capture the order the funds will not be collected by PayPal.

You can check out the PayPal onApprove documentation directly, here.

Support

If you assistance integrating the PayPal SDK please contact our support team.