Payment Form SDK

SmartPay offers a lightweight Web SDK that provides a simple solution to collect credit card data. The integration is similar to the regular Checkout Web SDK, i.e., renderWidget method triggers seamless credit card data collection form rendering and accepts the following options:

html-container id
js-callbacks: success/error
styling options

Payment Form SDK supports custom styling and all payment flows: guest payment, storing a new payment option and CIT-stored payment.

info

In case of CIT-Stored payments, stored payment option selection should be provided by integrator.

Introduction

Include SmartPay Stylesheet

The SmartPay Stylesheet Generator allows merchants to customize the look and feel of SmartPay components to align with their brand guidelines. It provides a pre-configured set of styles that can be adapted without modifying the core SDK code. This ensures a consistent experience across checkout flows.

To access the Stylesheet Generator, merchants can reach out to their dedicated Product Solution Specialist. Once access is granted, the tool is available at: https://smartpay.cons.stylesheet.jpmmps.com.

After generating the stylesheet using the SmartPay Stylesheet Generator, merchants must download the CSS file and host it directly on their own web server. This ensures full control over availability and performance, and avoids reliance on external resources. To apply the stylesheet to the checkout flow, include it in the following line in the <head> section of the website:

<link href="smartpay-style.css" rel="stylesheet"> 

Make sure the href path points to the correct location of the hosted file on your domain. This stylesheet must be loaded before the SmartPay Widget is rendered, so that styles are applied correctly.

Merchants must ensure that their web server is configured to allow SmartPay to access any required assets (e.g., fonts) by enabling cross-origin resource sharing (CORS) using the Access-Control-Allow-Origin header.

SmartPay widgets are styling using predefined CSS classes. These styles are applied automatically if the SmartPay stylesheet is already loaded on the merchant site. Component-level or granular styling is not supported.

Include SmartPay Web SDK

<script src="https://.../light-sdk/smp-bundle.js" type="text/javascript"></script> 

Please check Sandbox vs. Production page for latest URL.

Create containers

<div id="main-container"></div> 

Loading the bundle will initialize the SmartPay app instance and attach it to the window object.

const app = window.SmpLibrary.SmartPayAppInstance;

void renderWidget ( options );

Calling 'renderWidget' function will trigger the SmartPay to render the credit card payment form for the given payment checkout token into the provided container(s).

// Guest CIT
app.renderWidget({
  paymentCheckoutToken: '<payment checkout token here>',
  container: '<html container id here>',
  paymentFormOnly: true,
  purpose: 'PAYMENT_TRANSACTION',
  paymentOptionCode: 'CC',
  successHandler: function (data) {...},
  errorHandler: function (errorCode, error) {...}
});

// Card-on-File Registration for MIT
app.renderWidget({
  subscriptionCheckoutToken: '<subscription checkout token here>',
  container: '<html container id here>',
  paymentFormOnly: true,
  purpose: 'REGISTRATION',
  paymentOptionCode: 'CC',
  successHandler: function (data) {...},
  errorHandler: function (errorCode, error) {...}
});

// CIT-Stored (one-click payment)
app.renderWidget({
  paymentCheckoutToken: '<payment checkout token here>',
  container: '<html container id here>',
  paymentFormOnly: true,
  purpose: 'PAYMENT_TRANSACTION',
  storedPaymentOptionReference: '<stored card on file reference here>'
  successHandler: function (data) {...},
  errorHandler: function (errorCode, error) {...}
});

Configuration Options

The rendering method requires the configuration object containing the parameters reflecting your rendering choice.

Field	Description	Data Type	Mandatory
paymentCheckoutToken	Use the "checkoutToken" received in your Checkout API response.	string	Yes, if "subscriptionCheckoutToken" is not provided, provide "paymentOptionCode".
subscriptionCheckoutToken	Alternatively to "paymentCheckoutToken", provide "subscriptionCheckoutToken" received as part of the response of Create Subscription Checkout API to register new payment card.	string	Yes, if "paymentCheckoutToken" is not provided, and purpose is "Registration".
container	HTML element id of the selector-container. In multipage scenario, it is mandatory only for the first initialization, until the payment option is selected.	string	Yes
successHandler	Use this function to trigger any logic to be executed upon the transaction having been successfully processed.	function	Yes
errorHandler	Use this function to trigger any logic to be executed upon the transaction having been unsuccessfully processed.	function	Yes
paymentFormOnly	The parameter shows if the payment selector page should be rendered or not.	boolean	No
paymentOptionCode	The payment option code associated with the payment option chosen by the customer. Possible values: American Express = "AMEX", Apple Pay = "APPLPAY", Bacs Direct Debit = "BACSDD", Credit Card = "CC", Google Pay = "GGLPAY", JCB = "JCB", MASTERCARD = "MSTRCRD", Pay-by-Bank = "PAYBBNK", SEPA B2B = "SEPADDB2B", SEPA Core = "SEPADDCORE", VISA = "VISA".	enum	Conditional (required if: paymentFormOnly=true and purpose=REGISTRATION OR purpose=PAYMENT_TRANSACTION and storedPaymentOptionReference=null and paymentFormOnly=true).
storedPaymentOptionReference	The stored payment reference showing the registered payment option. Only for payment to distinguish between "guest" and "CIT Stored flow".	string	Conditional (required if: purpose=PAYMENT_TRANSACTION AND paymentOptionCode=null and paymentFormOnly=true).
purpose	Indicates the purpose of the checkout. Possible values: REGISTRATION PAYMENT_TRANSACTION If purpose="REGISTRATION", please register a new payment card.	enum	Conditional (required if paymentFormOnly=true).

Introduce success handling

When payment data has been submitted and processed by payment provider, the user journey is completed. SmartPay widget notifies merchant's website about it via "successHandler" callback function which needs to be provided.

Once received, the actual transaction status should be checked via getPaymentStatus API. To differentiate between regular payment completed and payment option registered, use "kind" value provided in data object.

function successHandler(data){ 
	if (data.kind === "CALLBACK"){ 
        // Process payment completed 

        // Request transaction status via Get Payment Status API 
		      // Link: https://documentation.jpmmps.com/docs/smartpay/get-payment-status-api/
    } 
    if (data.kind === "ADD_METHOD_CALLBACK"){ 
      // Process Card-on-File registration completed 
		    // Request updated payment options list via "Get Payment Options" API.
		    // Link: https://documentation.jpmmps.com/docs/smartpay/payment-option-management-apis

		    // Note: there is no any payment processed yet, no need to check status. 
    } 
} 
// Render payment form for Card-on-File Registration for MIT 
app.renderWidget({
  successHandler: successHandler,
  ...
  ...
});

Introduce error handling

Errors in the SmartPay Widget need to be handled through the callback function provided into the "renderWidget" method. The errorCode parameter contains the actual error code as per the table below. The second parameter of the callback provides the exact message of the error, to be used in debugging and as reference for our customer support.

function errorHandler(code, message) {
    console.error(code +': '+ message);     

    // handle the error
    // Request transaction status via Get Payment Status API
    // Link: https://documentation.jpmmps.com/docs/smartpay/get-payment-status-api/
}

app.renderWidget({
    ... 
    ... 
    errorHandler: errorHandler
});

Error code	Description	Consumer to select another payment method and retry
ERROR_INIT_PAYMENT	Error on payment initialization, consumer need to choose a different payment option.	Yes
ERR_CONFIG	Error while loading payment methods configuration or widget.	No
ERROR_INVALID_INPUT	Invalid configuration passed to `renderWidget` method.	No
ERR_PAYMENT_CALLBACK	Payment failed during Authorization or Capturing. This is a hard failure, recreation of transaction is required.	No
ERROR_INIT_STORE_PAYMENT_OPTION	Error while storing payment option, consumer need to choose a different payment option.	Yes
ERROR	Any other unhandled error.	No
ERROR_CHECKOUT_TIMEOUT	`checkoutToken` or `transactionId` is expired. Refer here for more details.	No

Please associate the "transactionId", "checkoutToken" and possible error messages with your business transaction / order inside your systems and make it available to your support / operation staff. It will be valuable input for any ticket to our support team.

Complete integration sample

<!DOCTYPE html> 
<html lang="en"> 
<head> 
    <script src="https://sdk.cons.smartpay.jpmmps.com/light-sdk/smp-bundle.js"></script> 
        <link rel="stylesheet" type="text/css" href="https://your-domain.com/style.css" class="none_scoped"> 
    <meta charset="UTF-8"> 
    <title>Light SDK integration</title> 
</head> 
<body> 
<div style="display: flex;justify-content: center;margin-top: 12px"> 
    <div style="display: flex;flex-direction: column;width: 80%"> 
        <div style="display:flex"><label for="checkoutTokenId" style="margin-right: 4px">CheckoutToken</label><input 
                type="text" 
                id="checkoutTokenId" 
                style="width: 100%"> 
        </div> 
        <input type="button" style="margin: 6px 0 6px 0" onclick="renderForm()" value="Render payment form"> 
        <div id="main-container"></div> 
    </div> 
</div> 
</body> 
<script> 
  function renderForm() { 
    const app = window.SmpLibrary.SmartPayAppInstance; 
app.renderWidget({ 
      paymentCheckoutToken: document.getElementById('checkoutTokenId').value, 
      container: 'main-container', 
      purpose: 'PAYMENT_TRANSACTION', 
      paymentOptionCode: 'CC', 
       successHandler: function (data) { 
    // Cleanup payment form container  
        if (data.kind === 'CALLBACK') { 
          // process payment completed 
          // Requests transaction status via Get Payment Status API 
          console.log(data); 
        } 
        if (data.kind === 'ADD_METHOD_CALLBACK') { 
          // optionally process payment option registration. 
          // Note: there is no any payment processed yet, no need to check status. 
          console.log(data); 
        } 
      }, 
      errorHandler: function (errorCode, error) { 
     // Cleanup payment form container  
// Requests transaction status via Get Payment Status API 
console.error(errorCode, error); 
      }, 
      paymentFormOnly: true, 
    }); 
  } 
</script> 
</html> 

Payment Form SDK

Introduction

Include SmartPay Stylesheet

Include SmartPay Web SDK

Render SmartPay Widget

Create containers

Render widget

Configuration Options

Introduce success handling

Introduce error handling

Complete integration sample

Introduction​

Include SmartPay Stylesheet​

Include SmartPay Web SDK​

Render SmartPay Widget​

Create containers​

Render widget​

Configuration Options​

Introduce success handling​

Introduce error handling​

Complete integration sample​

Introduction

Include SmartPay Stylesheet

Include SmartPay Web SDK

Render SmartPay Widget

Create containers

Render widget

Configuration Options

Introduce success handling

Introduce error handling

Complete integration sample