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 <head> tag of your payment page. Server domain information for each integration environment can be found in Getting Started > Server Information (Domain/Host).

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) #

<!-- JSP Example: Prevent caching by appending the system timestamp as a query parameter -->
<script src="https://{domain}/sdk/ebp-sdk.js?t=<%= System.currentTimeMillis() %>"></script>

Example using Pure HTML / JavaScript Dynamic Loading #

<!-- Example of dynamically loading the SDK using JavaScript -->
<script>
    (function() {
        const script = document.createElement('script');
        // Load with the domain corresponding to the integration environment and the current timestamp.
        script.src = 'https://{domain}/sdk/ebp-sdk.js?t=' + new Date().getTime();
        script.async = true;
        document.head.appendChild(script);
    })();
</script>

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

// 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	`object` 🟡 Conditional PG-specific configuration for Worldpay AWP transactions (Refer to Section 3 for details)
0	worldpay	`object` 🟡 Conditional PG-specific configuration for Worldpay HPP transactions
0	checkoutCom	`object` 🟡 Conditional PG-specific configuration for Checkout.com transactions
0	omise	`object` 🟡 Conditional PG-specific configuration for Omise transactions
0	spinner	`object` ⚪ Optional Configuration for customizing the loading indicator (spinner)
1	open	`function` ⚪ Optional Callback to show the loading indicator
1	close	`function` ⚪ Optional Callback to hide the loading indicator
0	onSuccess	`function` 🔴 Required Callback triggered upon successful payment
0	onFailure	`function` 🔴 Required 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 #

// 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	`object` 🔴 Required Selector configuration for EBP SDK to control HTML UI elements
1	submit	`string` 🔴 Required CSS Selector for the button that triggers payment processing
1	cardHolder	`string` 🔴 Required CSS Selector for the Card Holder Name input field
0	config	`object` 🔴 Required Hosted Fields configuration object passed to Worldpay Access Checkout SDK
1	form	`string` 🔴 Required CSS Selector for the payment form element
1	fields	`object` 🔴 Required Collection of CSS selectors for individual input fields
2	pan	`string\|object` 🔴 Required Selector for the Card Number (PAN) container
2	expiry	`string\|object` 🔴 Required Selector for the Expiry Date container
2	cvv	`string\|object` 🔴 Required Selector for the CVV container
1	styles	`object` ⚪ Optional CSS style rules applied within the Hosted Fields inputs