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.
Field | Type | Description |
---|---|---|
group_label | string | The platform Id of your store |
trace_id | string | Any string to help with debugging the logs. (We prefer to use public_order_id ) |
eps_url | string | Should be https://eps.secure.boldcommerce.com |
eps_bucket_url | string | Should be https://static-eps.secure.boldcommerce.com |
payment_gateways | Array | The payment gateway information that is provided in the order init endpoint |
callbacks | Array | More 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.
onClickPaymentOrder
: Calls when user click on any payment buttons like googlePay, applePay or PaypalonCreatePaymentOrder
: Calls when we need to create an order on the payment gateway side. (Only for PPCP implementation)onUpdatePaymentOrder
: Calls when user change their shipping information on the wallet payment UI to get the updated taxes or shipping lines information.onRequireOrderData
: Calls when Payment SDK needs any specific data.onApprovePaymentOrder
: Calls when user click on complete payment on the wallet payment UIonScaPaymentOrder
: Calls when Payment SDK needs to handle the SCA.onErrorPaymentOrder
: (optional) Calls when there is any error reported by payment gatewayonUpdateVisuals
: (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
- Render Payments
- 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,
- If customer is using payment buttons, the next steps are handled by the the callbacks when customers interact with the buttons.
- If customer is using card fields and they clicks to complete a payment, call these methods
getDataRequirements
andtokenize
. 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:
- The storefront calls the Process Order endpoint and receives a 202 error with a request body of
{"clientSecretToken": "token", }
. - The storefront calls the EPS tokenize request with the
client_secret_token
as a payload to in the request. - The payment SDK shows the SCA in fullscreen.
- Once the request is done, the storefront retries the Process Order endpoint.