Credit Card Module

This guide will walk you through integrating and configuring the component to capture and update user credit card details securely within your application.

Getting Started

Follow the three steps below for a basic implementation. This will render the UI for adding a new credit card.

Step 1: Add the HTML Container

First, place an empty div element with the ID i-payoutUI in your HTML file where you want the UI to be displayed.

<div id="i-payoutUI"></div>

Step 2: Install the Script

Next, include the creditCardModule.bundle.js script in your HTML page. Using the defer attribute is recommended.

<script defer src="creditCardModule.bundle.js"></script>

📘
Dynamic Script Loading
If the static script tag causes issues, you can load the script dynamically using JavaScript. This method programmatically creates a script tag and appends it to the document's body.
let creditCardModuleScript = document.createElement('script');

// Set the path to the bundle file
creditCardModuleScript.src = 'creditCardModule.bundle.js';
creditCardModuleScript.defer = true;
// Append the script to the body
document.body.appendChild(creditCardModuleScript);

Step 3: Configure the Module

Finally, create a <script> tag before the bundle script and define the global configuration object window.creditCardModuleConfig. You must provide the required properties to initialize the module.

When combined, a minimal HTML page will look like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>i-payout Drop-in UI</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <div id="i-payoutUI"></div>

    <script>
      window.creditCardModuleConfig = {
        authToken: 'YOUR_JWT_AUTH_TOKEN',
        beneficiaryToken: 'USER_BENEFICIARY_TOKEN',
        merchantId: 'YOUR_MERCHANT_ID'
      };
    </script>

    <script defer src="creditCardModule.bundle.js"></script>
  </body>
</html>

Configuration (`creditCardModuleConfig`)

The window.creditCardModuleConfig object controls the module's behavior and appearance.

Required Properties

These properties are mandatory for the module to function correctly.

Property	Type	Description
`authToken`	`string`	A JSON Web Token (JWT) used for authenticating API requests.
`beneficiaryToken`	`string`	The unique identifier for the user (beneficiary).
`merchantId`	`string`	The unique identifier for your merchant account.

Optional Properties

These properties allow you to enable different modes, handle events, and customize the UI.

Property	Type	Description
`creditCardToken`	`string`	The token for an existing credit card. Providing this switches the module to update mode.
`lang`	`string`	Sets the display language. Defaults to `"EN"`.
`events`	`object`	An object containing callback functions. See Event Handling.
`labels`	`object`	An object to override default UI text. See UI Customization.
`styles`	`object`	An object to customize the look and feel. See UI Customization.

Module Modes

The module can operate in two modes: adding a new card or updating an existing one.

Mode 1: Add a New Credit Card

To add a new card, provide only the three required properties. After a successful submission, the API response will contain a token for the new card, which you must capture using an event callback for future updates.

window.creditCardModuleConfig = {
  authToken: 'YOUR_JWT_AUTH_TOKEN',
  beneficiaryToken: 'USER_BENEFICIARY_TOKEN',
  merchantId: 'YOUR_MERCHANT_ID'
};

Mode 2: Update an Existing Credit Card

To fetch and update an existing card, include the optional creditCardToken property.

window.creditCardModuleConfig = {
  authToken: 'YOUR_JWT_AUTH_TOKEN',
  beneficiaryToken: 'USER_BENEFICIARY_TOKEN',
  merchantId: 'YOUR_MERCHANT_ID',
  creditCardToken: 'EXISTING_CREDIT_CARD_TOKEN' // <-- Add this to update
};

Event Handling & Callbacks

Callbacks allow you to capture the result of the user's submission. Events are passed within an events object in the main configuration.

Available Events

Event	Description	Parameters
`onComplete`	Fired when the "add" or "update" operation completes, successfully or with an error.	`(error, response)`

The onComplete callback receives two arguments: error and response. If the operation is successful, error will be null; otherwise, it will contain the error details.

Example: Capturing the `creditCardToken`

The following code presents the standard method for retrieving the token after a new credit card is added.

<script>
  // 1. Define the callback function to handle the result
  const handleCreditCardCompletion = (error, response) => {
    if (error) {
      // Handle the error case
      console.error('Operation failed:', error.message);
      alert(`Error ${error.statusCode}: ${error.message}`);
      return;
    }
    
    // 2. On success, process the response
    console.log('Operation successful!', response);
    
    // 3. Extract and store the new credit card token for future use
    const newCreditCardToken = response.data.token;
    console.log('New Credit Card Token:', newCreditCardToken);
    // e.g., saveTokenToYourDatabase(newCreditCardToken);
  };

  // 4. Assign the function to the onComplete event in the config
  window.creditCardModuleConfig = {
    authToken: 'YOUR_JWT_AUTH_TOKEN',
    beneficiaryToken: 'USER_BENEFICIARY_TOKEN',
    merchantId: 'YOUR_MERCHANT_ID',
    events: {
      onComplete: handleCreditCardCompletion
    }
  };
</script>

API Responses

The onComplete callback returns a standardized JSON object. When isSuccess is true, the data object contains the card's token.

Add Response Example

{
  "data": {
    "token": "dc2eb0bf-63bc-463c-b104-8c193a3499b4",
    "isDocumentVerificationRequired": false,
    "lstErrMessagesReqFields": [],
    "code": 0,
    "desc": "",
    "msgType": 0,
    "expire_in_seconds": 0
  },
  "isSuccess": true,
  "message": "Credit card added successfully",
  "statusCode": 0,
  "logIdentifier": "5ea63eb299a949c99794beba934021c5"
}

Update Response Example

The response for an update is nearly identical, with a different success message.

{
  "data": {
    "token": "dc2eb0bf-63bc-463c-b104-8c193a3499b4",
    // ... other properties
  },
  "isSuccess": true,
  "message": "Credit card updated successfully",
  "statusCode": 0,
  "logIdentifier": "5ea63eb299a949c99794beba934021c5"
}

UI Customization (Optional)

You can customize the text and appearance of the UI using the optional labels and styles properties.

`labels`

Override default text content like titles and button labels.

Property	Type	Default Value	Description
`widgetHeaderTitle`	`string`	`'Add or Update Credit Card'`	The main title at the top of the widget.
`submitButton`	`string`	`'Submit'`	Text for the final submission button.

`styles`

Customize the look and feel by providing CSS properties or class names. Each style property accepts an object containing a style object (for inline CSS) and/or a cssClass string (for external classes).

Property	Target Element
`widgetContainer`	The main wrapper of the entire UI component.
`widgetHeader`	The header section containing the title.
`widgetHeaderTitle`	The title text itself.
`formContainer`	The container wrapping the form fields.
`formControlsContainer`	The container wrapping the form input controls.
`sectionListMessageContainer`	The container for informational section messages.
`sectionTitle`	The section titles (e.g., "Card Information").
`sectionListMessage`	The text of an informational note within a section.
`formControlLabel`	The label for an individual input or dropdown.
`input`	All text input fields.
`dropdown`	All dropdown/select fields.
`validationMessage`	The text that appears for validation errors.
`submitButton`	The final submission button.

Customization Example

window.creditCardModuleConfig = {
  // ... required properties
  
  // Custom labels
  labels: {
    widgetHeaderTitle: 'Securely Add Your Card',
    submitButton: "Save Card",
  },

  // Custom styles
  styles: {
    widgetContainer: {
      style: {
        'box-shadow': '0 4px 8px rgba(0,0,0,0.1)',
        'border-radius': '8px',
      }
    },
    formContainer: {
        style: {
            'padding': '0 1rem'
        }
    },
    submitButton: {
      // Apply pre-existing CSS classes from your stylesheet
      cssClass: "btn btn-primary w-100"
    },
    validationMessage: {
      style: {
        'font-weight': 'bold'
      }
    }
  }
};