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:

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 our most popular and flexible option.

​

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.

​

Usage

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.

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

​

PayabliComponent className

The PayabliComponent className has the following methods:

Here’s an example:

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.

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:

/* ... 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:

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.

#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.

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

Here are examples of different input configurations:

​

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:

• Pure JavaScript, HTML, and CSS example
• ReactJS example

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 userful data you can access.

        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 doc.

​

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.