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

Applies to:Developers

Before integrating with this component, we highly recommend reading Embedded Components Overview to make sure you select the right component for your use case, authenticate properly, and understand how to style the components.

This page covers only the configuration unique to this component, and doesn’t cover all the basic usage for embedded components.

Use the PayMethod UI component to launch a modal that captures a customer payment method for tokenization and returns an ID. Use the ID make future transactions via API with the storedMethodId field.


This component is supported in the Playground. Use the Embedded Component Playground to edit and design embedded components in real time, and export the code to use in your own site or app.

You need to include <meta charset="UTF-8"> in the <head> element of your HTML to prevent problems with special characters such as ‘á’ or ‘ñ’.

Usage

The PayMethod UI component is a lightbox that’s displayed over content, you need an action or an event to trigger a function to display this modal.

See Library URLs for important information about embedded components library URLs.

Interactive demo

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.

Embedded content from https://files.buildwithfern.com/payabli.docs.buildwithfern.com/2025-07-01T20:17:18.824Z/snippets/demos/pay-method.html

PayMethod UI Demo

Loading content...

Configuration walkthrough

The interactive walkthrough displays code examples alongside step-by-step explanations.

Loading walkthrough content

Loading walkthrough...

Loading walkthrough...

/// Include the Payabli Script First, include the Payabli embedded component script in your HTML. This loads the core PayabliComponent class that powers all embedded components.

1<!DOCTYPE html>
2<html>
3<head>
4  <meta charset="UTF-8">
5  <title>Payabli Integration</title>
6</head>
7<body>
8  <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
9</body>
10</html>

/// Create the Container Add a container element where the embedded component renders. The configuration references this element by its id attribute.

This <div> element serves as the mounting point where the embedded component renders.

-9
1<!DOCTYPE html>
2<html>
3<head>
4  <meta charset="UTF-8">
5  <title>Payabli Integration</title>
6</head>
7<body>
8  <h1>Payment Form</h1>
9  <div id="pay-component-1"></div>
10  
11  <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
12</body>
13</html>

/// Configure the Component Create the configuration object that defines how your embedded component behaves. This configuration includes authentication tokens, payment method settings, and callback functions.

The rootContainer property connects the component to your HTML element by matching the id attribute value. The token value must be a public API token. See the Configuration Reference for more information.

-53
1<!DOCTYPE html>
2<html>
3  <head>
4    <meta charset="UTF-8">
5    <title>Payabli Integration</title>
6  </head>
7  <body>
8    <div id="pay-component-1"></div>
9    <button id="show-btn">Show Modal</button>
10    <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
11    <script>
12      var payabliConfig0 = {
13        type: "methodLightbox",
14        rootContainer: "pay-component-1",
15        buttonLabelInModal: 'Save Payment Method',
16        defaultOpen: 'ach',
17        hideComponent: true,
18        token: "your-public-api-token",
19        entryPoint: "your-entry-point",
20        card: {
21          enabled: true,
22          amex: true,
23          discover: true,
24          visa: true,
25          mastercard: true,
26          jcb: true,
27          diners: true,
28          fallbackAuth: true,
29        },
30        ach: {
31          enabled: true,
32          checking: true,
33          savings: false
34        },
35        customerData: {
36          customerNumber: "00001",
37          firstName: "John",
38          lastName: "Doe",
39          billingEmail: "johndoe@email.com"
40        }
41      }
42    </script>
43  </body>
44</html>

/// Add Callback Functions Implement success and error callback functions to handle component responses and form validation states.

These callback functions execute after the user submits payment information and the component receives a response from Payabli’s API.

-93
1<!DOCTYPE html>
2<html>
3<head>
4  <meta charset="UTF-8">
5  <title>Payabli Integration</title>
6  <style>
7    .hidden { display: none; }
8    #show-btn {
9      background: #4f46e5;
10      color: white;
11      padding: 12px 24px;
12      border: none;
13      border-radius: 6px;
14      cursor: pointer;
15      margin-top: 16px;
16    }
17  </style>
18</head>
19<body>
20  <h1>Payment Form</h1>
21  <div id="pay-component-1"></div>
22  <button id="show-btn">Show Modal</button>
23  <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
24  <script>
25    var payabliConfig0 = {
26      type: "methodLightbox",
27      rootContainer: "pay-component-1",
28      buttonLabelInModal: 'Save Payment Method',
29      defaultOpen: 'ach',
30      hideComponent: true,
31      token: "your-public-api-token",
32      entryPoint: "your-entry-point",
33      card: {
34          enabled: true,
35          amex: true,
36          discover: true,
37          visa: true,
38          mastercard: true,
39          jcb: true,
40          diners: true,
41          fallbackAuth: true,
42      },
43      ach: {
44          enabled: true,
45          checking: true,
46          savings: false
47      },
48      customerData: {
49          customerNumber: "00001",
50          firstName: "John",
51          lastName: "Doe",
52          billingEmail: "johndoe@email.com"
53      },
54      functionCallBackSuccess: function (response) {
55        // This callback covers both 2XX and 4XX responses
56        console.log(response);
57        switch (response.responseText) {
58          case "Success":
59            // Tokenization was successful
60            alert(`Success: ${response.responseData.resultText}`);
61            break;
62          case "Declined":
63            // Tokenization failed due to processor decline or validation errors
64            // Recommend reinitialization of the component so that the user can try again
65            // with different card data
66            alert(`Declined: ${response.responseData.resultText}`);
67            paycomponent0.payabliExec("reinit");
68            break;
69          default:
70            // Other response text. These are normally errors with Payabli internal validations
71            // before processor engagement
72            // We recommend reinitializing the component.
73            // If the problem persists, contact Payabli to help debug
74            alert(`Error: ${response.responseText}`);
75            paycomponent0.payabliExec("reinit");
76            break;
77        }
78      },
79      functionCallBackError: function (errors) {
80        // This callback covers 5XX response or parsing errors
81        console.log(errors);
82            // We recommend reinitializing the component.
83            // If the problem persists, contact Payabli to help debug
84        paycomponent0.payabliExec("reinit");
85      }
86    }
87  </script>
88</body>
89</html>

/// Initialize and Show Modal The final step creates a working payment method component that can securely save payment methods for future transactions.

-99
1<!DOCTYPE html>
2<html>
3<head>
4  <meta charset="UTF-8">
5  <title>Payabli Integration</title>
6  <style>
7    .hidden { display: none; }
8    #show-btn {
9      background: #4f46e5;
10      color: white;
11      padding: 12px 24px;
12      border: none;
13      border-radius: 6px;
14      cursor: pointer;
15      margin-top: 16px;
16    }
17    #pay-component-1 {
18      max-width: 500px;
19      margin: 20px 0;
20    }
21  </style>
22</head>
23<body>
24  <h1>Payment Form</h1>
25  <p>Click below to save a payment method:</p>
26  <div id="pay-component-1"></div>
27  <button id="show-btn">Show Modal</button>
28  <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
29  <script>
30    var payabliConfig0 = {
31      type: "methodLightbox",
32      rootContainer: "pay-component-1",
33      buttonLabelInModal: 'Save Payment Method',
34      defaultOpen: 'ach',
35      hideComponent: true,
36      token: "your-public-api-token",
37      entryPoint: "your-entry-point",
38      card: {
39          enabled: true,
40          amex: true,
41          discover: true,
42          visa: true,
43          mastercard: true,
44          jcb: true,
45          diners: true,
46          fallbackAuth: true,
47      },
48      ach: {
49          enabled: true,
50          checking: true,
51          savings: false
52      },
53      customerData: {
54          customerNumber: "00001",
55          firstName: "John",
56          lastName: "Doe",
57          billingEmail: "johndoe@email.com"
58      },
59      functionCallBackSuccess: function (response) {
60        // This callback covers both 2XX and 4XX responses
61        console.log(response);
62        switch (response.responseText) {
63          case "Success":
64            // Tokenization was successful
65            alert(`Success: ${response.responseData.resultText}`);
66            break;
67          case "Declined":
68            // Tokenization failed due to processor decline or validation errors
69            // Recommend reinitialization of the component so that the user can try again
70            // with different card data
71            alert(`Declined: ${response.responseData.resultText}`);
72            paycomponent0.payabliExec("reinit");
73            break;
74          default:
75            // Other response text. These are normally errors with Payabli internal validations
76            // before processor engagement
77            // We recommend reinitializing the component.
78            // If the problem persists, contact Payabli to help debug
79            alert(`Error: ${response.responseText}`);
80            paycomponent0.payabliExec("reinit");
81            break;
82        }
83      },
84      functionCallBackError: function (errors) {
85        // This callback covers 5XX response or parsing errors
86        console.log(errors);
87            // We recommend reinitializing the component.
88            // If the problem persists, contact Payabli to help debug
89        paycomponent0.payabliExec("reinit");
90      }
91    }
92
93    // Initialize the PayMethod component
94    var paycomponent0 = new PayabliComponent(payabliConfig0);
95    
96    // Add click handler to show the modal
97    document.getElementById('show-btn').addEventListener('click', function() {
98      paycomponent0.showModal();
99    });
100  </script>
101</body>
102</html>

You need to include <meta charset="UTF-8"> in the <head> element of your HTML to prevent problems with special characters such as ‘á’ or ‘ñ’.

Response example

For both ACH and card methods, a success response looks like this example. The referenceId is the ID you use as the storedMethodId in other operations.

See Handling responses and errors for more.

1response.responseText:
2"Success"
3
4response.responseData
5{"referenceId":"30e7658e-5c2c-4638-8308-b48edec0718b-1647","resultCode":1,"resultText":"Added","customerId":1647}

Next steps

The PayMethod component tokenizes the payment method, giving you an identifier for the saved method in the field responseData.ReferenceId. The identifier is associated with the customer. Use this identifier as the storedMethodId in the paymentMethod object to submit payments via the API.

Example: showModal and closeModal

You can show the component modal by calling showModal function, or close the component modal by calling closeModal function.

You can see an interactive version of this example on CodePen
1  <body>
2  <label>Creating a Payabli Object and showing the component (showModal) in a "click" event listener.<br />
3Closing the component modal (closeModal) in functionCallBackError.
4  </label>
5  <br />
6  <br />
7    <button id="btnx">Show Modal</button>
8    <div id="pay-component-1"></div>
9    <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
10    <script>
11        document.getElementById('btnx').addEventListener('click', showcomponent);
12        function showcomponent(){
13            var payabliConfig0 = {
14                type: "methodLightbox",
15                rootContainer: "pay-component-1",
16                buttonLabelInModal: 'Save Payment Method',
17                defaultOpen: 'ach',
18                hideComponent: true,
19                token: "o.z8j8aaztW9tUtUg4d..",
20                entryPoint: "bozeman-aikido",
21                card: {
22                    enabled: true,
23                    amex: true,
24                    discover: true,
25                    visa: true,
26                    mastercard: true,
27                    jcb: true,
28                    diners: true
29                },
30                ach: {
31                    enabled: true,
32                    checking: true,
33                    savings: false
34                },
35                customerData: {
36                    customerNumber: "00001",
37                    firstName: "John",
38                    lastName: "Doe",
39                    billingEmail: "johndoe@email.com"
40                },
41                functionCallBackSuccess: function (response) {
42                  const containerEl = document.querySelector('#pay-component-1');
43                  const responseText = JSON.stringify(response.responseText);
44                  const responseData = JSON.stringify(response.responseData);
45                  alert(responseText + " " + responseData);
46                  containerEl.innerHTML += `
47                    <hr/>
48                    <p><b>Embedded Component Response:</b></p>
49                    <p>${responseText}</p>
50                    <p>${responseData}</p>
51                    <hr/>
52                  `;
53                },
54                functionCallBackError: function (errors) {
55                    alert('Error!');
56                    console.log(errors);
57                    paycomponent.closeModal();
58                }
59            };
60
61            // Creating an instance of the component
62            if (typeof paycomponent == 'undefined'){
63                paycomponent = new PayabliComponent(payabliConfig0);
64            } else {
65                paycomponent.updateConfig(payabliConfig0);
66            }
67
68            paycomponent.showModal();
69        }
70    </script>
71  </body>

Configuration reference

These are the configuration parameters available for the PayMethod UI component.

The component accepts only the data below. If you need to pass more data than what’s supported, consider using the temporary token flow.

type
stringRequired

This value determines the type of embedded component to render.
Accepted values are: methodEmbedded, methodLightbox, vterminal, or expressCheckout.
For the PayMethod UI, this value is methodLightbox. See the Embedded Components Overview for more information on other component types.

rootContainer
stringRequired

Container ID used for the component.

defaultOpen
string

Sets the default payment method that’s shown. Accepted values are: card or ach.

buttonLabelInModal
string

Text label for the action button.

hideComponent
booleanDefaults to false

When true the component is hidden when it’s instanced.

token
stringRequired

API token for authentication.

forceCustomerCreation
booleanDefaults to true

When true, the component uses the customerData object to create a new customer record. When temporaryToken is true and forceCustomerCreation is false, the component doesn’t create a new customer record. See Temporary Token Flow for more information.

customCssUrl
string

Complete URL of a custom CSS stylesheet to use with the component.

temporaryToken
booleanDefaults to true

When true, the token created for the payment is temporary. Set this parameter to false to create a storedMethodId and save the payment profile.

card
objectRequired

cardService object used to configure accepted card types.

enabled
boolean

Enable/disable card option.

amex
boolean

Enable/disable acceptance of American Express cards.

discover
boolean

Enable/disable acceptance of Discover cards.

visa
boolean

Enable/disable acceptance of Visa cards.

mastercard
boolean

Enable/disable acceptance of MasterCard cards.

diners
boolean

Enable/disable acceptance of Diner’s Club cards.

jcb
boolean

Enable/disable acceptance of JCB cards.

inputs
object

Card input fields descriptors. This object applies only to the EmbeddedMethod UI component.

cardHolderName
object

Optional, but strongly recommended. Descriptor object for input field.

cardNumber
objectRequired

Descriptor object for input field.

cardExpirationDate
objectRequired

Descriptor object for input field.

cardCvv
objectRequired

Descriptor object for input field.

cardZipcode
object

Optional, but strongly recommended. Descriptor object for input field.

ach
objectRequired

achService object used to configure accepted ACH types.

enabled
boolean

Enable/disable ACH option.

checking
boolean

Enable/disable acceptance of Checking account.

savings
boolean

Enable/disable acceptance of Savings account.

achValidation
booleanDefaults to false

When set to true, the embedded component will validate ACH account and routing numbers in real time. This is an add-on feature. Contact the Payabli team for more information.

inputs
object

ACH input field descriptors. This only applies to the EmbeddedMethod UI component.

achAccountHolderName
objectRequired

Required. Descriptor object for input field.

achAccountType
objectRequired

Required. Descriptor object for input field.

achRouting
objectRequired

Required. Descriptor object for input field. Use the confirm input descriptor to add matching validation to this field. See Style Individual Fields for more.

achAccount
objectRequired

Required. Descriptor object for input field. Use the confirm input descriptor to add matching validation to this field. See Style Individual Fields for more.

paymentMethod
objectRequired

paymentMethod object with data related to the payment method. Required when saving a payment method or executing a payment. Can be passed to the component via payabliExec method.

customerData
objectRequired

Customer Object with data related to customer. Can be passed to the component via payabliExec method. Required when saving a payment method. Which fields are required depends on whether the paypoint has custom identifiers. If you aren’t using custom identifiers, then you must include at least one of these values: firstname and lastname, email, or customerId.

fallbackAuth
boolean | nullDefaults to false

When true, if tokenization fails, Payabli will attempt an authorization transaction to request a permanent token for the card. If the authorization is successful, the card will be tokenized and the authorization will be voided automatically.

fallbackAuthAmount
number | nullDefaults to 1.00

The amount for the fallbackAuth transaction. Defaults to one dollar.

functionCallBackSuccess
function

The callback function called when the component executes successfully.

functionCallBackError
function

The callback function called when the component receives an error. See functionCallBackError response in the next section for a complete reference.

functionCallBackReady
function

The callback function called when the component change status ready true or false after any input on the component.

Response object

The Response object received via a callback function has the following structure:

responseText
stringRequired

“Success” or “Declined”

responseData
objectRequired

Container for response details.

responseData.ReferenceId
string

Identifier for the transaction (for payments) or the stored payment method (for save payment method)

responseData.ResultCode
integer

Result of operation. 1 is success, 2 is declined, and 3 is error.

responseData.ResultText
string

Message related the result. If the operation was successful, it returns “Added”/“Approved”. If there was an error, it returns error details.

responseData.CustomerId
integer

ID for the customer owner of payment or saved payment method.