> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://beta-docs.payabli.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta-docs.payabli.com/_mcp/server.

# Embedded components overview

Embedded UI components are a JavaScript-based collection and tokenization system and a full payments API. You can use the embedded components in conjunction with the Payabli API to submit transactions or for other Payabli services that use payment information.

## Choose a component

To decide which embedded component to use, consider the functionality you need for your app. Payabli offers embedded components tailored to different use cases:

#### [EmbeddedMethod UI](/developer-guides/embedded-components-embeddedmethodui)

Capture a payment method or make a sale using any payment method. This is the most flexible component. It's ideal for tokenizing payment methods or making sales directly from your page.

#### [ExpressCheckout UI](/developer-guides/embedded-components-express-checkout)

Add acceptance for digital wallet payments like Apple Pay. It can be paired with other components to give your customer a range of options.

#### [VirtualTerminal UI](/developer-guides/embedded-components-virtualterminalui)

Embed a virtual terminal tool in your page or app, letting you add secure payment acceptance in a contained environment.

#### [PayMethod UI](/developer-guides/embedded-components-paymethodui)

Save payment method data without expanding your PCI scope. This component is a modal that opens over content, and is designed only for storing payment methods.

Which component is right for you depends on whether you need to make transactions, save payment method data, or both. For example, if you need to both save a payment method and execute payments, the EmbeddedMethod UI might be the best choice. If you just need to make transactions from your website or app, the VirtualTerminal UI could be the right choice. Overall, the EmbeddedMethod UI is the most popular and flexible option.

> **Tip**
>
> You can extend the EmbeddedMethod UI and PayMethod UI components even further by using a flow designed around returning a temporary payment token. See [Extend Embedded Components with the Temporary Token Flow](/developer-guides/tokenization-temporary-flow) for more.

## Library URLs

> **Info**
>
> See the [component.js Changelog](/changelog/embedded-components-changelog) to see the latest changes.
>
> Beginning October 22, 2023 embedded components no longer supports versions older than 1.9.0.

> **Note**
>
> See [Library URLs](/developer-guides/embedded-components-overview#library-urls) for important information about embedded components library URLs.

## Usage

> **Tip**
>
> Component configuration is covered in the **Configuration reference** section of the documentation for each component type.

Payabli designed the embedded components for flexibility. Implementation can be as uncomplicated as pasting a single script tag to your checkout page, or you can customize them to interact with your website. The components require loading the `component.js` library to work.

The `component.js` contains the code for the `PayabliComponent className`. You can use several instances of the `PayabliComponent className` in the same page extending the functionality provided in your application.

**`Sandbox`**

```javascript Sandbox
<script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
<script>
	var configuration = { ....};
	var payablicomponent = new PayabliComponent(configuration);
</script>
```

## Authentication

Authenticate via `token` key passed in the embedded component's configuration. Configuration is covered in the documentation for each component.

> **Note**
>
> The API token you use **must** be public, and if you are using a Creator component, the token must be set up for use with Creator. Learn more about [Payabli API tokens](/api-reference/api-overview#authentication).

## PayabliComponent className

The `PayabliComponent className` has the following methods:

**`showModal()`**

Shows the component if it's hidden.

---

**`closeModal()`**

Hides the component.

---

**`updateConfig()`**

Replaces the component configuration. See [this CodePen](https://codepen.io/payablidocs/pen/JjwezWa) for an example.

---

**`payabliExec(action, parameters)`**

Triggers an action. Valid actions are `method`, `pay`, `auth` and `reinit`. `parameters` is an optional structure that lets you dynamically overwrite the matching fields passed via configuration for `customerData` and `paymentDetail`.

#### actions

**`method`**

This action executes only a tokenization of the payment information (saves the payment method). This is the default action.

---

**`pay`**

This action executes a payment.

---

**`auth`**

This action executes only an authorization that needs to be captured later.

---

**`reinit`**

The reinit action resets the component, allowing for reuse in the same web page or session.

---

---

Here's an example:

```javascript
var dynamicData= { 
	customerData: {
    firstName: 'John',
    lastName: 'Doe'
  },
  paymentDetails: {
    totalAmount: 11.55
	}
};
mycomponent.payabliExec('pay', dynamicData); //This action executes a payment, using the customerData and paymentDetails objects declared in the dynamicData variable
```

## Customize component styling

Customize your component by providing a URL to a custom CSS file in the parameter `customCssUrl` in the component configuration.

**`CSS URL example`**

```js CSS URL example
const payabliConfig0 = {
          type: "methodLightbox",
          rootContainer: "pay-component-1",
          buttonLabelInModal: 'Save Payment Method',
          defaultOpen: 'ach',
          hideComponent: true,
          customCssUrl: 'www.example.com/mycssfile.css',
          ...
}
```

### Make the component background transparent

By default, the embedded components have a white background. To make the component's background transparent, add the following CSS to the stylesheet that's linked with the `customCssUrl` parameter:

```css
/* ... the rest of your custom css ... */

/* transparent while loading */
#main-loading-layer {
    background-color: transparent !important;
}

/* transparent after loading */
body {
    background-color: transparent !important;
}
```

### Component containers

Each component creates a container for the iframe with a specific ID:

* EmbeddedMethod: `payabliComponentsIframeContainerMethodEmbedded`
* PayMethod: `payabliComponentsIframeContainerMethod `
* VirtualTerminal: `payabliComponentsIframeContainerEterminal`

### Component elements

You can also make reference and create custom styles for specific elements inside of the component using these IDs:

<table>
  <thead>
    <tr>
      <th>
        ID
      </th>

      <th>
        Element
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `cardNumber`
      </td>

      <td>
        Card number input
      </td>
    </tr>

    <tr>
      <td>
        `cardNumberContainer`
      </td>

      <td>
        Card number container
      </td>
    </tr>

    <tr>
      <td>
        `cardExpirationDate`
      </td>

      <td>
        Card expiration date input
      </td>
    </tr>

    <tr>
      <td>
        `cardExpirationDateContainer`
      </td>

      <td>
        Card expiration date container
      </td>
    </tr>

    <tr>
      <td>
        `cardCvv`
      </td>

      <td>
        Card CVV input
      </td>
    </tr>

    <tr>
      <td>
        `cardCvvContainer`
      </td>

      <td>
        Card CVV container
      </td>
    </tr>

    <tr>
      <td>
        `cardZipcode`
      </td>

      <td>
        Card zip code input
      </td>
    </tr>

    <tr>
      <td>
        `cardZipcodeContainer`
      </td>

      <td>
        Card zip code container
      </td>
    </tr>

    <tr>
      <td>
        `cardHolderName`
      </td>

      <td>
        Cardholder name input
      </td>
    </tr>

    <tr>
      <td>
        `cardHolderNameContainer`
      </td>

      <td>
        Cardholder name container
      </td>
    </tr>

    <tr>
      <td>
        `achAccountType`
      </td>

      <td>
        Bank account type selector
      </td>
    </tr>

    <tr>
      <td>
        `achAccountTypeContainer`
      </td>

      <td>
        Bank account type container
      </td>
    </tr>

    <tr>
      <td>
        `achAccountHolderName`
      </td>

      <td>
        Bank account holder input
      </td>
    </tr>

    <tr>
      <td>
        `achAccountHolderNameContainer`
      </td>

      <td>
        Bank account holder container
      </td>
    </tr>

    <tr>
      <td>
        `achRouting`
      </td>

      <td>
        Bank routing input
      </td>
    </tr>

    <tr>
      <td>
        `achRoutingContainer`
      </td>

      <td>
        Bank routing container
      </td>
    </tr>

    <tr>
      <td>
        `achAccount`
      </td>

      <td>
        Bank account input
      </td>
    </tr>

    <tr>
      <td>
        `achAccountContainer`
      </td>

      <td>
        Bank account container
      </td>
    </tr>
  </tbody>
</table>

This example targets the card number, expiration date, CVV, ZIP code, and cardholder name fields. It adds a solid, 1 pixel black border to the fields.

```css
#cardNumber, #cardExpirationDate, #cardCvv, #cardZipcode, #cardHolderName{
  border: solid 1px #000000;
}
```

### Style individual fields

Components are flexible widgets. You can array the input fields inside of the container and change labels and placeholders. The component doesn't have a button triggering any action so you need to create one via code.

The internal design of the component is a grid with 3 rows and 12 columns. This feature allows developers to specify size and placement of each input in the grid without any CSS manipulation.

<table>
  <tbody>
    <tr>
      <td>
        Row 0
      </td>

      \{Array.from({ length: 12 }, (_, index) => (
              \<td key={index} style={{ border: '1px solid #CCCCCC', textAlign: 'center', color: '#333333', padding: '5px' }}>Size=1</td>
            ))}
    </tr>

    <tr>
      <td>
        Row 1
      </td>

      Size=2

      Size=3

      Size=5

      <td>
        Size=1
      </td>

      <td>
        Size=1
      </td>
    </tr>

    <tr>
      <td>
        Row 2
      </td>

      Size=8

      Size=4

      <td>
        Size=1
      </td>
    </tr>
  </tbody>
</table>

You can style inputs in the component configuration using these parameters:

<table id="inputdescriptor">
  <thead>
    <tr>
      <th>
        Field/Parameter
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        label
      </td>

      <td>
        string. Label for input field.
      </td>
    </tr>

    <tr>
      <td>
        placeholder
      </td>

      <td>
        string. Placeholder for input field.
      </td>
    </tr>

    <tr>
      <td>
        floating
      </td>

      <td>
        boolean. Enable/disable floating label within input field. Default is
        **true**
      </td>
    </tr>

    <tr>
      <td>
        value
      </td>

      <td>
        string. Value for input field.
      </td>
    </tr>

    <tr>
      <td>
        size
      </td>

      <td>
        integer. Size of input field in columns (1-12).
      </td>
    </tr>

    <tr>
      <td>
        row
      </td>

      <td>
        integer. Row to place the input within component grid (0-2), 0 being the
        top row.
      </td>
    </tr>

    <tr>
      <td>
        order
      </td>

      <td>
        integer. Order of input field within the row (0-99+), 0 being the left
        position.
      </td>
    </tr>

    <tr>
      <td>
        confirm
      </td>

      <td>
        boolean. For `achRouting` and `achAccount` inputs
        only. When `true`, duplicates the ACH account number and
        routing number fields and requires that the fields match. This helps
        make sure the user enters valid account and routing numbers.
        Only available for the EmbeddedMethod UI.
      </td>
    </tr>

    <tr>
      <td>
        country
      </td>

      <td>
        array\[string]. For `cardZipcode` input only. Accepted values
        are `us` and `ca`. Controls which zip code formats
        are accepted. If `ca` is included, then Canadian payments are enabled.
      </td>
    </tr>
  </tbody>
</table>

Here are examples of different input configurations:

**`Card field configuration example`**

```js Card field configuration example
card: {
    enabled: true,
    amex: true,
    discover: true,
    visa: true,
    mastercard: true,
    jcb: true, 
    diners: true,
    inputs: { 
        cardNumber: {
            size: 4,
            row: 1,
            order: 0,
            label: "Your Card Number"
        },
        cardExpirationDate: {
            size: 4,
            row: 1,
            order: 1,
        },
        cardZipcode: {
            label: "ZIP/POSTAL CODE",
            placeholder: "Zip/Postal Code",
            floating: false,
            size: 6,
            row: 2,
            order: 1,
            country: ["us", "ca"]
        }
    }
},

```

**`ACH field configuration example`**

```js ACH field configuration example
ach: {
  enabled: true,
  checking: true,
  savings: true,
  inputs: {
      achRouting: {
        label: "Routing Number",
        size: 6,
        row: 1,
        order: 0,
        confirm: false // Display the field twice to ensure the fields match
      },
      achAccount: { 
        label: "Account Number",
        size: 6,
        row: 2,
        order: 0, 
        confirm: true 
      }
  }
}
```

### Example without customizations

This is the look of the EmbeddedMethod component without customizations:

**Card**

*[See this example in CodePen](https://codepen.io/Luis-Payabli/pen/OJQBmdy)*

![](https://files.readme.io/6f0ff63-Screen_Shot_2022-06-07_at_3.41.48_PM.png)

**ACH**

*[See this example in CodePen](https://codepen.io/Luis-Payabli/pen/mdXGjxW)*

![](https://files.readme.io/eda763b-Screen_Shot_2022-06-07_at_4.08.44_PM.png)

### Example with customizations

This is an example of the EmbeddedMethod component with a custom CSS file and using input field descriptors.

*See this example in CodePen:*

* [Pure JavaScript, HTML, and CSS example](https://codepen.io/Luis-Payabli/pen/VwQGGaW)
* [ReactJS example](https://codepen.io/Luis-Payabli/pen/LYrVGpB)

Notice how the `functionCallBackReady` is triggered when the input fields are validated in the component showing or hiding the Submit button.

![](https://files.readme.io/a379ba9-Screen_Shot_2022-06-13_at_4.27.14_PM.png)

## Handling responses and errors

Responses are returned in `functionCallBackSuccess` and `functionCallBackError`.

This is a general response handling example. Check the response object reference for the embedded component you're using for other useful data you can access.

**`Response Handling Example`**

```js Response Handling Example
        functionCallBackSuccess: function (response) {

          // This callback covers both 2XX and 4XX responses
          console.log(response);
          switch (response.responseText) {
            case "Success":

              // Tokenization was successful
              alert(`Success: ${response.responseData.resultText}`);
              break;
            case "Declined":

              /* Transaction or tokenization failed due to processor decline or validation errors
              Recommend reinitialization of the component so that the user can try again
              with different card data */
              alert(`Declined: ${response.responseData.resultText}`);
              paycomponent0.payabliExec("reinit");
              break;
            default:

              /* Other response text. These are normally errors with Payabli internal validations
              before processor engagement. We recommend reinitializing the component.
              If the problem persists, contact Payabli to help debug */
              alert(`Error: ${response.responseText}`);
              paycomponent0.payabliExec("reinit");
              break;
          }
        },

        functionCallBackError: function (errors) {

          // This callback covers 5XX response or parsing errors
          console.log(errors);

          /* We recommend reinitializing the component.
          If the problem persists, contact Payabli to help debug */
          paycomponent0.payabliExec("reinit");
        }
```

Learn more about response codes and errors in [the reference](/references/return-codes-and-errors#ach-response-codes).

## Playground

The [Embedded Component Playground](https://playground.payabli.com) lets you experiment with some component types with a live preview in your browser. Learn more about the Playground in the [changelog](/changelog/2024#october-22).