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 for more information.

Choose a component

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

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

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.

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 for each component for more information about configuration options.

1
<script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
2
<script>
3
	var configuration = {...};
4
	var payablicomponent = new PayabliComponent(configuration);
5
</script>

Library URLs

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 for more information.

PayabliComponent class

The PayabliComponent class has the following methods:

1
var dynamicData= { 
2
	customerData: {
3
    firstName: 'John',
4
    lastName: 'Doe'
5
  },
6
  paymentDetails: {
7
    totalAmount: 11.55
8
  }
9
};
10
11
// This action executes a payment using the customerData and paymentDetails objects 
12
// declared in the dynamicData variable 
13
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.

1
const payabliConfig0 = {
2
  type: "methodLightbox",
3
  rootContainer: "pay-component-1",
4
  buttonLabelInModal: 'Save Payment Method',
5
  defaultOpen: 'ach',
6
  hideComponent: true,
7
  customCssUrl: 'www.example.com/mycssfile.css',
8
  ...
9
}

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:

1
/* ... the rest of your custom css ... */
2
3
/* transparent while loading */
4
#main-loading-layer {
5
    background-color: transparent !important;
6
}
7
8
/* transparent after loading */
9
body {
10
    background-color: transparent !important;
11
}

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:

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.

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

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.

Input configuration reference

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

Input configuration examples

Here are some examples of different input configurations:

1
card: {
2
    enabled: true,
3
    amex: true,
4
    discover: true,
5
    visa: true,
6
    mastercard: true,
7
    jcb: true, 
8
    diners: true,
9
    inputs: { 
10
        cardNumber: {
11
            size: 4,
12
            row: 1,
13
            order: 0,
14
            label: "Your Card Number"
15
        },
16
        cardExpirationDate: {
17
            size: 4,
18
            row: 1,
19
            order: 1,
20
        },
21
        cardZipcode: {
22
            label: "ZIP/POSTAL CODE",
23
            placeholder: "Zip/Postal Code",
24
            floating: false,
25
            size: 6,
26
            row: 2,
27
            order: 1,
28
            country: ["us", "ca"]
29
        }
30
    }
31
},

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.

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.

Customized

This is an example of the EmbeddedMethod component with customized input fields and configuration switching logic. See the Interactive demo for EmbeddedMethod UI for a live preview of this example.

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:

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 for each component to see more information about the response object.

1
functionCallBackSuccess: function (response) {
2
3
  // This callback covers both 2XX and 4XX responses
4
  console.log(response);
5
  switch (response.responseText) {
6
    case "Success":
7
8
      // Tokenization was successful
9
      alert(`Success: ${response.responseData.resultText}`);
10
      break;
11
12
    case "Declined":
13
14
      /* Transaction or tokenization failed due to processor decline or validation errors
15
      Recommend reinitialization of the component so that the user can try again
16
      with different card data */
17
      alert(`Declined: ${response.responseData.resultText}`);
18
      paycomponent0.payabliExec("reinit");
19
      break;
20
21
    default:
22
23
      /* Other response text. These are normally errors with Payabli internal validations
24
      before processor engagement. We recommend reinitializing the component.
25
      If the problem persists, contact Payabli to help debug */
26
      alert(`Error: ${response.responseText}`);
27
      paycomponent0.payabliExec("reinit");
28
      break;
29
  }
30
}

See Payment response codes and errors 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
• ExpressCheckout UI: ExpressCheckout UI documentation.

Playground

The Embedded Component Playground lets you experiment with some component types with a live preview in your browser.