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 open a modal that captures a customer payment method for tokenization. The captured payment method is returned as 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.

Usage

The PayMethod UI component is a modal that’s displayed over content and can be triggered via an event listener or function. Use the interactive demo to see how the component works, then follow the configuration walkthrough to set it up in your project.

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-09-15T12:20:56.870Z/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. Including <meta charset="UTF-8"> in the <head> element prevents problems with special characters such as ‘á’ or ‘ñ’.

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.

-50
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. These functions can call the closeModal and payabliExec methods to manage the embedded component’s state.

-91
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            paycomponent0.closeModal();
62            break;
63          case "Declined":
64            // Tokenization failed due to processor decline or validation errors
65            // Recommend reinitialization of the component so that the user can try again
66            // with different card data
67            alert(`Declined: ${response.responseData.resultText}`);
68            paycomponent0.payabliExec("reinit");
69            break;
70          default:
71            // Other response text. These are normally errors with Payabli internal validations
72            // before processor engagement
73            // We recommend reinitializing the component.
74            // If the problem persists, contact Payabli to help debug
75            alert(`Error: ${response.responseText}`);
76            paycomponent0.payabliExec("reinit");
77            break;
78        }
79      },
80      functionCallBackError: function (errors) {
81        // This callback covers 5XX response or parsing errors
82        console.log(errors);
83            // We recommend reinitializing the component.
84            // If the problem persists, contact Payabli to help debug
85        paycomponent0.payabliExec("reinit");
86      }
87    }
88  </script>
89</body>
90</html>

/// Initialize and Show Modal

The final step creates a working payment method component that can securely save payment methods for future transactions. Add a click handler to the button that calls the showModal method to display the embedded component.

-100
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            paycomponent0.closeModal();
67            break;
68          case "Declined":
69            // Tokenization failed due to processor decline or validation errors
70            // Recommend reinitialization of the component so that the user can try again
71            // with different card data
72            alert(`Declined: ${response.responseData.resultText}`);
73            paycomponent0.payabliExec("reinit");
74            break;
75          default:
76            // Other response text. These are normally errors with Payabli internal validations
77            // before processor engagement
78            // We recommend reinitializing the component.
79            // If the problem persists, contact Payabli to help debug
80            alert(`Error: ${response.responseText}`);
81            paycomponent0.payabliExec("reinit");
82            break;
83        }
84      },
85      functionCallBackError: function (errors) {
86        // This callback covers 5XX response or parsing errors
87        console.log(errors);
88            // We recommend reinitializing the component.
89            // If the problem persists, contact Payabli to help debug
90        paycomponent0.payabliExec("reinit");
91      }
92    }
93
94    // Initialize the PayMethod component
95    var paycomponent0 = new PayabliComponent(payabliConfig0);
96    
97    // Add click handler to show the modal
98    document.getElementById('show-btn').addEventListener('click', function() {
99      paycomponent0.showModal();
100    });
101  </script>
102</body>
103</html>

Configuration reference

These are the configuration parameters available for the PayMethod component. If you need to pass more than data than what’s supported, consider using the temporary token flow. See Temporary Token Flow for more information.

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.

Response

The embedded component returns a response object to the callback functions defined in the configuration. The response object contains the result of the transaction (success, declined, or error) and details about the transaction.

Response examples

Click the tab to see an example response returned by the embedded component for each result.

1{
2  responseText: "Success",
3  responseData: {
4    referenceId: "187-c5892026d9f345ffa63bf909d574fe92",
5    resultCode: 1,
6    resultText: "Added",
7    customerId: 1636,
8    methodReferenceId: "187-c5892026d9f345ffa63bf909d574fe92"
9  }
10}

Response reference

The response object passed to 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). The referenceId is used as the storedMethodId in other operations. See Handling responses and errors for more.

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.

responseData.methodReferenceId
string

Identifier for stored payment method for saved payment methods. This field has a value of null for payment transactions. The methodReferenceId is used as the storedMethodId in other operations. See Handling responses and errors for more.

functionCallBackError response

The functionCallBackError function is called when the component can’t validate the payment information before submitting it to Payabli’s API. The response object passed to functionCallBackError contains an array with codes, keys, and descriptions of failed validations. You can check the values in the array to offer your customized error message.

CodeKeyDescription
802paymentMethodsCardNumberErrorError in Card number field
803paymentMethodsCardExpirationDateErrorError in Card Expiration field
804paymentMethodsCardCvvErrorError in CardCVV field
805paymentMethodsCardZipcodeErrorError in Card Zip code field
901paymentMethodsAchAccountHolderNameErrorError in ACH Holder field
902paymentMethodsAchAccountTypeErrorError in ACH Account type field
903paymentMethodsAchRoutingErrorError in ACH Routing field
904paymentMethodsAchAccountErrorError in ACH Account number field