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. Go to CodePen to see a full working example of this component.


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

Step 1: Include the Payabli component

Add the script to the <body> element of your HTML.

Sandbox
1<!DOCTYPE html>
2<html>
3<head>
4  <meta charset="UTF-8">
5</head>
6<body>
7  <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
8</body>
9</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 ‘ñ’.

Step 2: Define the component container

Add the container to your HTML. This <div> tag is where the page renders the component. The ID is the identifier for rootContainer in your component configuration.

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

Step 3: Configure the component

Define the component configuration in a script block immediately after component.js and create an instance of the component.

Skip to the configuration reference section

In the example below the component modal is hidden by default. In this case you need a button to show the component on demand. Notice that the value for hideComponent in the configuration is true. This value hides the modal by default.

Full configuration example
1<body>
2  <div id="pay-component-1"></div>
3  <button id="btnx">Show Modal</button>
4  <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
5  <script>
6      document.getElementById('btnx').addEventListener('click', showcomponent);
7      var payabliConfig0 = {
8          type: "methodLightbox",
9          rootContainer: "pay-component-1",
10          buttonLabelInModal: 'Save Payment Method',
11          defaultOpen: 'ach',
12          hideComponent: true,
13          token: "o.z8j8aaztW9tUtUg4dlVeYAx+L2MazOFGr0DY8yuK3u79MCYlGK4/q0t5AD1UgLAjXOohnxN8VTZfPswyZcwtChGNn1a8jFMmYWHmLN2cPDW9IrBt1RtrSuu+85HJI+4kML5sIk9SYvULDAU2k0X0E1KFYcPwjmmkUjktrEGtz48XCUM70aKUupkrTh8nL7CXpAXATzVUZ2gEld9jGINwECPPLWmu+cZ4CJb7QMJxnzKFD073+nq/eL+pMth7+u/SkmAWC0+jn8y+Lf6T5Q5PqB6wN7Mvosp8g7U7lbEW2wC0DA92pjblfDHVJOQUkjgT7B1GvryMokLvBjoiaLhKa55iKZE1YDlyqruILkoNF+zGSPS9r17qU6w4ziKhoMdSPzPBJBlLhQhz3MVANXbjfEfJwmtr/JJ1uStUfBFJ710cS1x7goxMJO/cl+q+LVtPy788EKFkgMc5OjfBNCsNL+dBDVbK5CiIJUSbOFzdqdjY/VJ14MEodsHYOwMAjuF4.KRFMeEj0SOur8MLZ362c/UZ/U/Az3CSUkr3/8EVDE6Y=",
14          entryPoint: "bozeman-aikido",
15          card: {
16              enabled: true,
17              amex: true,
18              discover: true,
19              visa: true,
20              mastercard: true,
21              jcb: true,
22              diners: true,
23              fallbackAuth: true,
24          },
25          ach: {
26              enabled: true,
27              checking: true,
28              savings: false
29          },
30          customerData: {
31              customerNumber: "00001",
32              firstName: "John",
33              lastName: "Doe",
34              billingEmail: "johndoe@email.com"
35          },
36
37          functionCallBackSuccess: function (response) {
38            // This callback covers both 2XX and 4XX responses
39            console.log(response);
40            switch (response.responseText) {
41              case "Success":
42                // Tokenization was successful
43                alert(`Success: ${response.responseData.resultText}`);
44                break;
45              case "Declined":
46                // Tokenization failed due to processor decline or validation errors
47                // Recommend reinitialization of the component so that the user can try again
48                // with different card data
49                alert(`Declined: ${response.responseData.resultText}`);
50                paycomponent0.payabliExec("reinit");
51                break;
52              default:
53                // Other response text. These are normally errors with Payabli internal validations
54                // before processor engagement
55                // We recommend reinitializing the component.
56                // If the problem persists, contact Payabli to help debug
57                alert(`Error: ${response.responseText}`);
58                paycomponent0.payabliExec("reinit");
59                break;
60            }
61          },
62
63          functionCallBackError: function (errors) {
64            // This callback covers 5XX response or parsing errors
65            console.log(errors);
66                // We recommend reinitializing the component.
67                // If the problem persists, contact Payabli to help debug
68            paycomponent0.payabliExec("reinit");
69          }
70
71
72      var paycomponent0 = new PayabliComponent(payabliConfig0);
73
74      function showcomponent(){
75        paycomponent0.showModal();
76      }
77  </script>
78</body>

You are ready to use the component in your web page.

Step 4: Style the component

Information about styling embedded components is available in Embedded Components Overview.

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.z8j8aaztW9tUtUg4dlVeYAx+L2MazOFGr0DY8yuK3u79MCYlGK4/q0t5AD1UgLAjXOohnxN8VTZfPswyZcwtChGNn1a8jFMmYWHmLN2cPDW9IrBt1RtrSuu+85HJI+4kML5sIk9SYvULDAU2k0X0E1KFYcPwjmmkUjktrEGtz48XCUM70aKUupkrTh8nL7CXpAXATzVUZ2gEld9jGINwECPPLWmu+cZ4CJb7QMJxnzKFD073+nq/eL+pMth7+u/SkmAWC0+jn8y+Lf6T5Q5PqB6wN7Mvosp8g7U7lbEW2wC0DA92pjblfDHVJOQUkjgT7B1GvryMokLvBjoiaLhKa55iKZE1YDlyqruILkoNF+zGSPS9r17qU6w4ziKhoMdSPzPBJBlLhQhz3MVANXbjfEfJwmtr/JJ1uStUfBFJ710cS1x7goxMJO/cl+q+LVtPy788EKFkgMc5OjfBNCsNL+dBDVbK5CiIJUSbOFzdqdjY/VJ14MEodsHYOwMAjuF4.KRFMeEj0SOur8MLZ362c/UZ/U/Az3CSUkr3/8EVDE6Y=",
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.