# Embedded components overview

> Learn how to use Payabli's embedded components to create customized checkout experiences without handling sensitive payment information yourself

<AudienceInfo audiences={['developers']} />

Payabli offers a set of embedded JavaScript UI components that let you create customized checkout experiences without handling sensitive payment information.
You can use the embedded components to process transactions or save payment methods while remaining PCI compliant.
Payment methods saved via the embedded components can be used with the Payabli API to perform functions like subscriptions, queries, and more.
See [Tokenization Overview](/guides/platform-tokenization-overview) for more information.

## Choose a component

Use the interactive quiz below to find the right embedded component for your application.

<ComponentChooser />

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

<CardGroup cols={2}>
  <Card title="EmbeddedMethod UI" href="/guides/pay-in-components-embeddedmethod-ui">
    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.
  </Card>

  <Card title="ExpressCheckout UI" href="/guides/pay-in-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.
  </Card>

  <Card title="VirtualTerminal UI" href="/guides/pay-in-components-virtual-terminal-ui">
    Embed a virtual terminal tool in your page or app, letting you add secure payment acceptance in a contained environment.
  </Card>

  <Card title="PayMethod UI" href="/guides/pay-in-components-paymethod-ui">
    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.
  </Card>
</CardGroup>

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](/guides/platform-developer-tokenization-temp-flow) for more.
</Tip>

## Usage

Payabli's embedded components are customizable and easy to implement.
To load Payabli's embedded components, add a script tag that points to Payabli's `component.js` library.
After adding the script tag, create an instance of the `PayabliComponent` class with your configuration.
See the [Configuration reference](/guides/pay-in-components-embeddedmethod-ui#configuration-reference) for each component for more information about configuration options.

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

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

### Library URLs

<Info>
  See the [component.js Changelog](/developers/embedded-components/changelog) to see the latest changes.

  Beginning October 22, 2023 embedded components no longer supports versions older than 1.9.0.
</Info>

The sandbox and production library URLs are evergreen, meaning that the URL always points to the latest version.

* Sandbox: `https://embedded-component-sandbox.payabli.com/component.js`
* Production: `https://embedded-component.payabli.com/component.js`

You must add the `data-test` configuration variable to your script tag when using the sandbox library. Don't include `data-test` when working with the production library.

### Authentication

Payabli's embedded components authenticate with the `token` field passed in the embedded component's configuration.
The API token must be a public token. If you are using a Creator component, the API token must be set up for the Creator.
See [Payabli API tokens](/developers/api-reference/api-overview#authentication) for more information.

### `PayabliComponent` class

The `PayabliComponent` class has the following methods:

<ParamField path="showModal()">
  Show the component if it's hidden.
</ParamField>

<ParamField path="closeModal()">
  Hide the component.
</ParamField>

<ParamField path="updateConfig()">
  Replace the component configuration.
</ParamField>

<ParamField path="payabliExec(action, parameters)">
  Trigger 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`.

  <Expandable title="actions">
    <ParamField path="method">
      This action executes a tokenization of the payment information (saves the payment method). This action doesn't process a payment. This is the default action.
    </ParamField>

    <ParamField path="pay">
      This action processes a payment.
    </ParamField>

    <ParamField path="auth">
      This action processes an authorization that needs to be captured later. This action doesn't process a payment.
    </ParamField>

    <ParamField path="reinit">
      This action resets the component state. We recommend using this method when the component is in an error or declined state and you want to retry a transaction.
    </ParamField>
  </Expandable>
</ParamField>

```javascript payabliExec example
var dynamicData= { 
	customerData: {
    firstName: 'John',
    lastName: 'Doe'
  },
  paymentDetails: {
    totalAmount: 11.55
  }
};

// This action executes a payment using the customerData and paymentDetails objects 
// declared in the dynamicData variable 
mycomponent.payabliExec('pay', dynamicData); 
```

## Customize styles

To customize the component's styles, you can pass a URL to a CSS file in the `customCssUrl` parameter of the component configuration.

```js customCssUrl 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

The embedded components are loaded inside of an iframe.
Each component creates a container for the iframe with a specific ID.
You can use these IDs to target the component container in your CSS or JavaScript code.
Here are the IDs for each component:

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

### Component elements

You can also reference specific elements inside of the component and create custom styles for them.
The elements inside the component have the following IDs:

<div>
  <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>
</div>

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 Form style example
#cardNumber, #cardExpirationDate, #cardCvv, #cardZipcode, #cardHolderName {
  border: solid 1px #000000;
}
```

## Customize input fields

The input fields inside of the component can be styled individually via the component's configuration object.

### Input grid layout

The component's inputs are laid out in a grid with 3 rows and 12 columns.
You can specify size and placement of each input in the grid without any CSS by using the `row`, `order`, and `size` fields.

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

      <td>
        Size=1
      </td>

      <td>
        Size=1
      </td>

      <td>
        Size=1
      </td>

      <td>
        Size=1
      </td>

      <td>
        Size=1
      </td>

      <td>
        Size=1
      </td>

      <td>
        Size=1
      </td>

      <td>
        Size=1
      </td>

      <td>
        Size=1
      </td>

      <td>
        Size=1
      </td>

      <td>
        Size=1
      </td>

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

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

      <td colSpan={2}>
        Size=2
      </td>

      <td colSpan={3}>
        Size=3
      </td>

      <td colSpan={5}>
        Size=5
      </td>

      <td>
        Size=1
      </td>

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

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

      <td colSpan={8}>
        Size=8
      </td>

      <td colSpan={4}>
        Size=4
      </td>
    </tr>
  </tbody>
</table>

### Input configuration reference

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

<ParamField path="label" type="string">
  Label for input field.
</ParamField>

<ParamField path="placeholder" type="string">
  Placeholder for input field.
</ParamField>

<ParamField path="floating" type="boolean" default="true">
  Enable/disable floating label within input field.
</ParamField>

<ParamField path="value" type="string">
  Value for input field.
</ParamField>

<ParamField path="size" type="integer">
  Size of input field in columns (1-12).
</ParamField>

<ParamField path="row" type="integer">
  Row to place the input within component grid (0-2), 0 being the top row.
</ParamField>

<ParamField path="order" type="integer">
  Order of input field within the row (0-99+), 0 being the left position.
</ParamField>

<ParamField path="confirm" type="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.
</ParamField>

<ParamField path="country" type="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.
</ParamField>

### Input configuration examples

Here are some examples of different input configurations:

<CodeBlocks>
  ```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"]
          }
      }
  },
  ```

  ```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 
        }
    }
  }
  ```
</CodeBlocks>

## Interactive demos

The following demos show the EmbeddedMethod UI component with different configurations.

### Card

This is a basic example of the EmbeddedMethod UI component with default card configuration.
This demo shows the component in action with transaction processing and visual feedback.
When the component processes a transaction, the demo displays the JSON response.

<EmbeddedIframe src="https://files.buildwithfern.com/payabli.docs.buildwithfern.com/138379df07febcb006b2454fbf4b217eca4043060498dab2c44f27833c259997/snippets/demos/overview-plain-card.html" title="Basic Card Demo" height="400px" />

### ACH

This is a basic example of the EmbeddedMethod UI component with default ACH configuration.
This demo shows the component in action with transaction processing and visual feedback.
When the component processes a transaction, the demo displays the JSON response.

<EmbeddedIframe src="https://files.buildwithfern.com/payabli.docs.buildwithfern.com/fc90cda186b33e7198c8bcf17630d3085682a827cf6a0e8b641502a6387ead8a/snippets/demos/overview-plain-ach.html" title="Basic ACH Demo" height="400px" />

### RDC

This is a basic example of the EmbeddedMethod UI component with default RDC configuration.
This demo shows the component in action with transaction processing and visual feedback.
When the component processes a transaction, the demo displays the JSON response.

<EmbeddedIframe src="https://files.buildwithfern.com/payabli.docs.buildwithfern.com/dac334e1102afbccd950197618ae3330d989be4d80a5ef565c65a141400998cf/snippets/demos/overview-plain-rdc.html" title="Basic RDC Demo" height="400px" camera={true} />

### Customized

This is an example of the EmbeddedMethod component with customized input fields and configuration switching logic.
See the [Interactive demo for EmbeddedMethod UI](/guides/pay-in-components-embeddedmethod-ui#interactive-demo) for a live preview of this example.

<Frame caption="Customized EmbeddedMethod UI">
  <img src="https://files.buildwithfern.com/payabli.docs.buildwithfern.com/0a45c12008fa4b82466a4238248d358eabdf7caed1f632739cead7d1b771b791/images/customized-embedded-method.png" alt="Customized EmbeddedMethod UI" />
</Frame>

## Handle responses and errors

The embedded components return response objects to callback functions that you define in the component configuration.
You can use these callback functions to handle responses and errors, such as displaying messages to users.

There are four possible callback functions that are triggered based on the component's state:

* `functionCallBackSuccess`: Triggered for successful transactions (2XX responses) and declined transactions (4XX responses).
* `functionCallBackError`: Triggered for validation errors.
* `functionCallBackReady`: Triggered when the component is ready to process a transaction.
* `functionCallBackCancel`: Triggered when the user closes the component's modal.

### Callback support reference

The callback functions supported are different for each component type.
The following table shows which callback functions are supported by each component type:

<table>
  <thead>
    <tr>
      <th>
        Component
      </th>

      <th>
        Callback
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        EmbeddedMethod UI
      </td>

      <td>
        functionCallBackSuccess, functionCallBackReady, functionCallBackError
      </td>
    </tr>

    <tr>
      <td>
        PayMethod UI
      </td>

      <td>
        functionCallBackSuccess, functionCallBackError
      </td>
    </tr>

    <tr>
      <td>
        VirtualTerminal UI
      </td>

      <td>
        functionCallBackSuccess, functionCallBackError
      </td>
    </tr>

    <tr>
      <td>
        ExpressCheckout UI
      </td>

      <td>
        functionCallBackSuccess, functionCallBackReady, functionCallBackError, functionCallBackCancel
      </td>
    </tr>
  </tbody>
</table>

### Declined transactions

For a declined transaction, the `functionCallBackSuccess` callback is triggered.
To determine whether a transaction was successful or declined, check the `responseText` field in the response object.
A successful transaction returns `"Success"` in the `responseText` field, and a declined transaction returns `"Declined"`.
After a declined transaction, we recommend calling the `payabliExec("reinit")` method to reinitialize the component so that the user can try again.

This example shows how to handle successful transactions, declined transactions, and internal Payabli processing errors.
See the [Response reference](/guides/pay-in-components-embeddedmethod-ui#response-reference) for each component to see more information about the response object.

```js functionCallBackSuccess 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;
  }
}
```

See [Payment response codes and errors](/guides/platform-return-codes-and-errors-reference#ach-response-codes) for more information about server errors and response codes.

### Error handling

The `functionCallbackError` callback is triggered for validation errors.
You can use this callback to display custom error messages to users or log errors for debugging.

The `functionCallBackError` callback has a different response object based on the component type:

* EmbeddedMethod UI, PayMethod UI, VirtualTerminal UI: [`functionCallBackError` response](/guides/pay-in-components-embeddedmethod-ui#functioncallbackerror-response)
* ExpressCheckout UI: [ExpressCheckout UI documentation](/guides/pay-in-components-express-checkout#functioncallbackerror-response).

## Playground

The [Embedded Component Playground](https://playground.payabli.com) lets you experiment with some component types with a live preview in your browser.

## Related resources

See these related resources to help you get the most out of Payabli.

<AccordionGroup>
  <Accordion title="Next steps">
    * **[EmbeddedMethod UI](/guides/pay-in-components-embeddedmethod-ui)** - Learn how to use the EmbeddedMethod UI embedded component to add the ability to securely store a payment profile or execute a sale
    * **[ExpressCheckout UI](/guides/pay-in-components-express-checkout)** - Learn how to use the ExpressCheckout UI component on your site or in your app to securely accept digital wallet payments
    * **[Embedded components framework integrations](/guides/pay-in-developer-components-frameworks)** - Learn how to use Payabli's embedded components with front-end frameworks like React and Vue
    * **[PayMethod UI](/guides/pay-in-components-paymethod-ui)** - Learn how to use the PayMethod UI embedded component to securely store a payment profile with a low-code modal-based UI.
    * **[VirtualTerminal UI](/guides/pay-in-components-virtual-terminal-ui)** - Learn how to use the VirtualTerminal UI component on your site or in your app to securely accept payments
  </Accordion>

  <Accordion title="References">
    * **[Payment methods for testing](/guides/test-accounts-reference)** - Use these payment methods to test your integration with Payabli
    * **[Payment response codes and errors](/guides/platform-return-codes-and-errors-reference)** - Learn about payment response codes for different payment methods
  </Accordion>

  <Accordion title="Related topics">
    * **[Extend embedded components with the temporary token flow](/guides/platform-developer-tokenization-temp-flow)** - Use the temporary token flow with embedded components to have complete control over user transaction experience without expanding PCI scope
  </Accordion>
</AccordionGroup>