# EBP SDK Guide (ebp-sdk.js)
> **Current SDK Version:** `v0.1.0`
EBP SDK is a Client-side JavaScript SDK designed to help you easily and securely integrate payment screens and encryption capabilities.
---
## 1. SDK Loading
To use the EBP SDK, you must load `ebp-sdk.js` within the `` tag of your payment page.
Server domain information for each integration environment can be found in [Getting Started > Server Information (Domain/Host)](/docs/overview/getting-started#1.2.1).
### Cache Busting
To prevent the browser from caching older versions of the SDK, which could lead to unexpected behavior after updates, you must add a **timestamp** as a query parameter dynamically when loading the script.
#### Example using Backend Templates (JSP/Thymeleaf)
```html
```
#### Example using Pure HTML / JavaScript Dynamic Loading
```html
```
---
## 2. SDK Initialization & Payment Triggering
You initialize the SDK and prepare the payment process by invoking `window.EbpSdk.processPayment(response, config)` with the response object (`response`) received from the merchant backend [Create Payment Intent API](/docs/api-endpoints/purchase/payment-intents) and a merchant configuration object (`config`).
> [!NOTE]
> **Dynamic PG Routing and Configuration Notes**
> When you call the Payment Intents API via the backend and pass the response, the PG (Payment Gateway) for the transaction is automatically determined based on the payment method and context (country, currency, etc.).
> Accordingly, required options within the `config` object passed to `processPayment` may vary based on the `response.data.pgResult.pgProvider` value. (e.g., if `pgProvider` is `WORLDPAY_AWP`, the `worldpayAwp` configuration described below must be provided.)
>
> You can pre-check supported PG information and detailed integration specifications for each payment method using the [Payment Specification Inquiry API](/docs/api-endpoints/billing/capacity).
```javascript
// Assume that we have received the response from the payment-intents API call
const response = {
// ... payment-intents response data
};
// SDK Configuration Object
const config = {
// PG-specific settings (Conditional: Required depending on the dynamically determined pgProvider)
worldpayAwp: {
// ... (Refer to '3. Worldpay AWP Configuration' for details)
},
// (Optional) Custom Spinner Callbacks
spinner: {
open: function() {
console.log('Spinner Open');
},
close: function() {
console.log('Spinner Close');
}
},
// Payment Success Callback (Common Mandatory)
onSuccess: function(result) {
alert('Payment has been completed.');
console.log('Result:', result);
},
// Payment Failure Callback (Common Mandatory)
onFailure: function(error) {
alert('An error occurred during payment processing.');
console.error('Error:', error);
}
};
// Initialize SDK and prepare for payment
window.EbpSdk.processPayment(response, config);
```
### Configuration Options
| depth | Field | Details & Description |
| :---- | :----------- | :-------------------- |
| 0 | worldpayAwp | [type:object] [req:Conditional] [desc:PG-specific configuration for Worldpay AWP transactions (Refer to Section 3 for details)] |
| 0 | worldpay | [type:object] [req:Conditional] [desc:PG-specific configuration for Worldpay HPP transactions] |
| 0 | checkoutCom | [type:object] [req:Conditional] [desc:PG-specific configuration for Checkout.com transactions] |
| 0 | omise | [type:object] [req:Conditional] [desc:PG-specific configuration for Omise transactions] |
| 0 | spinner | [type:object] [req:Optional] [desc:Configuration for customizing the loading indicator (spinner)] |
| 1 | open | [type:function] [req:Optional] [desc:Callback to show the loading indicator] |
| 1 | close | [type:function] [req:Optional] [desc:Callback to hide the loading indicator] |
| 0 | onSuccess | [type:function] [req:Yes] [desc:Callback triggered upon successful payment] |
| 0 | onFailure | [type:function] [req:Yes] [desc:Callback triggered upon payment failure] |
---
## 3. Worldpay AWP Configuration
When using Worldpay AWP (Access Worldpay), the `worldpayAwp` property must be provided in the `config` object.
This configuration is separated into the `config` area (used for Worldpay Checkout SDK initialization) and the `elements` area (used for internal UI binding).
Specifically, **`elements.submit`** and **`elements.cardHolder`** are **Required** for the payment process.
### Example
```javascript
// response from payment-intents (where pgProvider is 'WORLDPAY_AWP')
const response = {
// ... payment-intents response data
};
const config = {
worldpayAwp: {
// Element selectors for EBP SDK UI control (Mandatory)
elements: {
submit: "#pay-btn",
cardHolder: "#card-holder"
},
// Configuration passed directly to Worldpay Access Checkout SDK (Mandatory)
config: {
form: "#payment-form",
fields: {
pan: "#card-number",
expiry: "#card-expiry",
cvv: "#card-cvv"
},
// Inline styles for Worldpay Hosted Fields (Optional)
styles: {
'input': {
'font-size': '16px',
'color': '#333333'
}
}
}
},
spinner: {
open: function() { console.log('Spinner Open'); },
close: function() { console.log('Spinner Close'); }
},
onSuccess: function(result) {
alert('Payment has been completed.');
console.log('Result:', result);
},
onFailure: function(error) {
alert('Payment failed.');
console.error('Error:', error);
}
};
window.EbpSdk.processPayment(response, config);
```
### Worldpay AWP Configuration Details (`worldpayAwp`)
| depth | Field | Details & Description |
| :---- | :--------- | :-------------------- |
| 0 | elements | [type:object] [req:Yes] [desc:Selector configuration for EBP SDK to control HTML UI elements] |
| 1 | submit | [type:string] [req:Yes] [desc:CSS Selector for the button that triggers payment processing] |
| 1 | cardHolder | [type:string] [req:Yes] [desc:CSS Selector for the Card Holder Name input field] |
| 0 | config | [type:object] [req:Yes] [desc:Hosted Fields configuration object passed to Worldpay Access Checkout SDK] |
| 1 | form | [type:string] [req:Yes] [desc:CSS Selector for the payment form element] |
| 1 | fields | [type:object] [req:Yes] [desc:Collection of CSS selectors for individual input fields] |
| 2 | pan | [type:string\|object] [req:Yes] [desc:Selector for the Card Number (PAN) container] |
| 2 | expiry | [type:string\|object] [req:Yes] [desc:Selector for the Expiry Date container] |
| 2 | cvv | [type:string\|object] [req:Yes] [desc:Selector for the CVV container] |
| 1 | styles | [type:object] [req:Optional] [desc:CSS style rules applied within the Hosted Fields inputs] |