Embedded components overview

Applies to:Developers

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.

The embedded components capture payment information without expanding your PCI scope. The components are PCI compliant, so you can use them to collect payment information without having to handle sensitive data. See Tokenization Overview for more information.

Choose a component

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

A wizard that helps you choose the right embedded component for your payment integration. You are on step 1 of 3.

1. What do you need to do?

Use arrow keys to navigate options, Enter or Space to select, Escape to clear focus.

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

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

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

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

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.

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.

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

Library URLs

See the component.js Changelog to see the latest changes.

Beginning October 22, 2023 embedded components no longer supports versions older than 1.9.0.

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.

Usage

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.

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>

Authentication

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

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.

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 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:

1 var dynamicData= { 
2 	customerData: {
3     firstName: 'John',
4     lastName: 'Doe'
5   },
6   paymentDetails: {
7     totalAmount: 11.55
8 	}
9 };
10 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

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

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:

ID	Element
`cardNumber`	Card number input
`cardNumberContainer`	Card number container
`cardExpirationDate`	Card expiration date input
`cardExpirationDateContainer`	Card expiration date container
`cardCvv`	Card CVV input
`cardCvvContainer`	Card CVV container
`cardZipcode`	Card zip code input
`cardZipcodeContainer`	Card zip code container
`cardHolderName`	Cardholder name input
`cardHolderNameContainer`	Cardholder name container
`achAccountType`	Bank account type selector
`achAccountTypeContainer`	Bank account type container
`achAccountHolderName`	Bank account holder input
`achAccountHolderNameContainer`	Bank account holder container
`achRouting`	Bank routing input
`achRoutingContainer`	Bank routing container
`achAccount`	Bank account input
`achAccountContainer`	Bank account container

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 }

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.

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

Row 0

Row 1

Size=2

Size=3

Size=5

Size=1

Row 2

Size=8

Size=4

Size=1

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

Field/Parameter	Description
label	string. Label for input field.
placeholder	string. Placeholder for input field.
floating	boolean. Enable/disable floating label within input field. Default is true
value	string. Value for input field.
size	integer. Size of input field in columns (1-12).
row	integer. Row to place the input within component grid (0-2), 0 being the top row.
order	integer. Order of input field within the row (0-99+), 0 being the left position.
confirm	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.
country	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.

Here are 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 },

Example without customizations

This is the look of the EmbeddedMethod component without customizations:

Card

See this example in CodePen

ACH

See this example in CodePen

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:

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

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

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             case "Declined":
12 
13               /* Transaction or tokenization failed due to processor decline or validation errors
14               Recommend reinitialization of the component so that the user can try again
15               with different card data */
16               alert(`Declined: ${response.responseData.resultText}`);
17               paycomponent0.payabliExec("reinit");
18               break;
19             default:
20 
21               /* Other response text. These are normally errors with Payabli internal validations
22               before processor engagement. We recommend reinitializing the component.
23               If the problem persists, contact Payabli to help debug */
24               alert(`Error: ${response.responseText}`);
25               paycomponent0.payabliExec("reinit");
26               break;
27           }
28         },
29 
30         functionCallBackError: function (errors) {
31 
32           // This callback covers 5XX response or parsing errors
33           console.log(errors);
34 
35           /* We recommend reinitializing the component.
36           If the problem persists, contact Payabli to help debug */
37           paycomponent0.payabliExec("reinit");
38         }

Learn more about response codes and errors in the reference.

Playground

The Embedded Component Playground lets you experiment with some component types with a live preview in your browser. Learn more about the Playground in the changelog.