Skip to main content

Integrate the Payments SDK

Integrate Bold's Payments SDK with your store to combine your store's existing frontend with Bold's payment options and capabilities, including increased security for your customers' payment data.

The Payments SDK is how your store communicates with Bold's payment service. For more information on how Bold handles payment data, refer to the EPS overview.

Bold's provide bold hosted templated (one page and three page) which can be use if you want to avoid doing this integration.

Follow these steps to integrate the Payments SDK with your store's frontend.

Adding the Javascript SDK

Load the following Payments SDK script to the page where you want to load payment buttons, card fields, or both.

<script src="https://static-eps.secure.boldcommerce.com/js/payments_sdk.js"></script>

Creating the div container

Create HTML elements for where the buttons or card fields will be rendered. You will need to pass this when calling the payment SDK functions.

Initialize the Bold Order

Initialize a checkout order using the Bold initialize order endpoint.

For more details on how to create an order, refer to this guide.

Initializing the bold payment SDK instance

Initialize a new bold.Payments instance. Make sure that this is only initiated once.

const boldPayments = new window.bold.Payments(initialData);

The bold Payment SDK requires initialData with the following data.

FieldTypeDescription
group_labelstringThe platform Id of your store
trace_idstringAny string to help with debugging the logs. (We prefer to use public_order_id)
eps_urlstringShould be https://eps.secure.boldcommerce.com
eps_bucket_urlstringShould be https://static-eps.secure.boldcommerce.com
payment_gatewaysArrayThe payment gateway information that is provided in the order init endpoint
callbacksArrayMore details are provided below

Callbacks

The payment SDK can required some data from the the storefront in order to process the payment. These callbacks are defined by the storefront in order to work properly with the payment SDK.

  1. onClickPaymentOrder: Calls when user click on any payment buttons like googlePay, applePay or Paypal
  2. onCreatePaymentOrder: Calls when we need to create an order on the payment gateway side. (Only for PPCP implementation)
  3. onUpdatePaymentOrder: Calls when user change their shipping information on the wallet payment UI to get the updated taxes or shipping lines information.
  4. onRequireOrderData: Calls when Payment SDK needs any specific data.
  5. onApprovePaymentOrder: Calls when user click on complete payment on the wallet payment UI
  6. onScaPaymentOrder: Calls when Payment SDK needs to handle the SCA.
  7. onErrorPaymentOrder: (optional) Calls when there is any error reported by payment gateway
  8. onUpdateVisuals: (optional) Calls if there is any UI changes done by the payment SDK.

Here is an example of how to define a callback function:

export async function onRequireOrderData(requirements: Array<IRequirementDataType>):Promise<IOrderDataPayload> {
const appState = getApplicationState();

const dataPayload: IOrderDataPayload = {};
requirements.forEach(rq => {
switch (rq) {
case 'customer':
dataPayload[rq] = {
first_name: appState.customer.first_name,
last_name: appState.customer.last_name,
email_address: appState.customer.email_address,
};
break;
case 'billing_address':
dataPayload[rq] = appState.addresses.billing;
break;
case 'shipping_address':
dataPayload[rq] = appState.addresses.shipping;
break;
...
}
});

return dataPayload;
}

Render Methods

On the new instance, call the render methods. there are two render functions

  1. Render Payments
  2. Render Wallet Payments

Render Payments

It renders the Wallets pays along with the credit card fields. Here is an example on how to call this function.

boldPayments
.renderPayments(divContainer)
.then(() => {
// handle anything that need to be done after payment iframe is shows
})
.catch((e: Error) => {
// do error handling here
});

Once you initialize this function,

  1. If customer is using payment buttons, the next steps are handled by the the callbacks when customers interact with the buttons.
  2. If customer is using card fields and they clicks to complete a payment, call these methods getDataRequirements and tokenize. Here is the example.
const requirements = boldPayments.getDataRequirements();
const dataPayload: ITokenizePayload = {};
requirements.forEach(rq => {
switch (rq) {
case 'customer':
// provide customer information to dataPayload
break;
case 'billing_address':
// provide billing address to dataPayload
break;
case 'shipping_address':
// provide shipping address to dataPayload
break;
});

boldPayments.tokenize(dataPayload).then(() => {
// call process order endpoint
}).catch((e) => {
// do error handling
});

Render Wallet Payments

It only renders the wallet payment buttons like applePay, googlePay or Paypal etc.

boldPayments
.renderWalletPayments(divContainer)
.then(() => {
// handle anything that need to be done after payment iframe is shows
})
.catch((e: Error) => {
// do error handling here
});

The next steps for wallet payment are handled by the the callbacks when customers interact with the buttons.

Implementing Strong Customer Authentication (SCA)

If the merchant and customer are both located in Europe, you may be required to complete additional verification of the customer's identity to comply with Strong Customer Authentication (SCA). Bold completes this authentication using 3D Secure (3DS) technology, which is displayed within the SPI iframe.

The following steps outline the process of successfully handling SCA on an order:

  1. The storefront calls the Process Order endpoint and receives a 202 error with a request body of {"clientSecretToken": "token", }.
  2. The storefront calls the EPS tokenize request with the client_secret_token as a payload to in the request.
  3. The payment SDK shows the SCA in fullscreen.
  4. Once the request is done, the storefront retries the Process Order endpoint.