Pay InEmbedded components

EmbeddedMethod UI

Learn how to use the EmbeddedMethod UI embedded component to add the ability to securely store a payment profile or execute a sale

Applies to:Developers

Use the EmbeddedMethod component to capture a payment method or make a sale using any payment method. This is the most flexible and customizable component Payabli offers to developers. To see a working example of this component, go to CodePen.


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

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.

See the Configuration section for a full configuration reference.

1<!DOCTYPE html>
2<html>
3  <head>
4    <meta charset="UTF-8">
5    <style>
6      .hidden {
7        display: none;
8      }
9      #pay-component-1 {
10        max-width: 510px;
11      }
12    </style>
13  </head>
14  <body>
15    <p>When the form is valid, the action button is shown.</p>
16    <div id="pay-component-1"></div>
17    <button id="btnx" class="hidden">Submit</button>
18    <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
19    <script>
20      document.getElementById("btnx").addEventListener("click", executeAction);
21      var payabliConfig0 = {
22        type: "methodEmbedded",
23        rootContainer: "pay-component-1",
24        defaultOpen: "card", //offering only Card method - Embedded UI can only show a payment method
25        //customCssUrl: "your url to a custom css file",
26        token: "your Payabli API Token", //must be a public token
27        entryPoint: "test",
28        card: {
29          enabled: true,
30          amex: true,
31          discover: true,
32          visa: true,
33          mastercard: true,
34          jcb: true,
35          diners: true,
36          fallbackAuth: true,
37          inputs: {
38            //here we are customizing the input fields
39            cardHolderName: {
40              label: "NAME ON CARD",
41              placeholder: "",
42              floating: false,
43              value: "John Doe",
44              size: 12,
45              row: 0,
46              order: 0,
47            },
48            cardNumber: {
49              label: "CARD NUMBER",
50              placeholder: "1234 1234 1234 1234",
51              floating: false,
52              size: 6,
53              row: 1,
54              order: 0,
55            },
56            cardExpirationDate: {
57              label: "EXPIRATION DATE",
58              placeholder: "MM/YY",
59              floating: false,
60              size: 6,
61              row: 1,
62              order: 1,
63            },
64            cardCvv: {
65              label: "CVV/CVC",
66              placeholder: "CVV/CVC",
67              floating: false,
68              size: 6,
69              row: 2,
70              order: 0,
71            },
72            cardZipcode: {
73              label: "ZIP/POSTAL CODE",
74              placeholder: "ZIP/POSTAL CODE",
75              floating: false,
76              size: 6,
77              row: 2,
78              order: 1,
79              country: ["us", "ca"],
80            },
81          },
82        },
83        ach: {
84          enabled: false,
85          checking: true,
86          savings: true,
87        },
88        customerData: {
89          customerNumber: "00001",
90          firstName: "John",
91          lastName: "Doe",
92          billingEmail: "johndoe@email.com",
93        },
94        functionCallBackSuccess: function (response) {
95          // This callback covers both 2XX and 4XX responses
96          console.log(response);
97          switch (response.responseText) {
98            case "Success":
99              // Tokenization was successful
100              alert(`Success: ${response.responseData.resultText}`);
101              break;
102            case "Declined":
103              // Transaction or tokenization failed due to processor decline or validation errors
104              // Recommend reinitialization of the component so that the user can try again
105              // with different card data
106              alert(`Declined: ${response.responseData.resultText}`);
107              paycomponent0.payabliExec("reinit");
108              break;
109            default:
110              // Other response text. These are normally errors with Payabli internal validations
111              // before processor engagement
112              // We recommend reinitializing the component.
113              // If the problem persists, contact Payabli to help debug
114              alert(`Error: ${response.responseText}`);
115              paycomponent0.payabliExec("reinit");
116              break;
117          }
118        },
119        functionCallBackReady: function (data) {
120          //Callback function to capture the ready state of the component.
121          //The callback receives an array of booleans with 2 positions: index 0 is for ach, index 1 is for card.
122          //In our example we are offering card payment method so we need to verify the position 1 in array "data".
123          //When the captured value is "true" we are showing the button to execute the action, when it is "false" we hide it.
124          var btn = document.getElementById("btnx");
125          if (data[1] === true) {
126            btn.classList.remove("hidden");
127          } else {
128            if (!btn.classList.contains("hidden")) {
129              btn.classList.add("hidden");
130            }
131          }
132        },
133        functionCallBackError: function (errors) {
134          // This callback covers 5XX response or parsing errors
135          console.log(errors);
136          // We recommend reinitializing the component.
137          // If the problem persists, contact Payabli to help debug
138          paycomponent0.payabliExec("reinit");
139        }
140      }
141      var paycomponent0 = new PayabliComponent(payabliConfig0);
142    </script>
143
144  </body>
145</html>

Step 4: Style the component

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

Step 5: Execute an action

You can use the embedded component to execute a payment or to save the payment method. The action is triggered via the payabliExec function in the instanced className. This example calls a JS function named executeAction when the component is ready and the user clicks the button.

Learn more about payabliExec in the Embedded Components Overview.

1  <!DOCTYPE html>
2  <html>
3  <head>
4    <meta charset="UTF-8">
5    <style>
6      .hidden {
7          display: none;
8      }
9      #pay-component-1 {
10          max-width: 510px;
11      }
12      iframe {
13          border: solid 1px transparent;
14      }
15      button {
16          background-image: -webkit-linear-gradient(0deg, #7121ff 0%, #21d4fd 100%);
17          background-image: -moz-linear-gradient(0deg, #7121ff 0%, #21d4fd 100%);
18          background-image: -ms-linear-gradient(0deg, #7121ff 0%, #21d4fd 100%);
19          border: none;
20          padding: 15px 30px;
21          color: #ffffff;
22          font-size: 12px;
23          cursor: pointer;
24          text-transform: uppercase;
25          font-weight: bold;
26          border-radius: 5px;
27          width: 100%;
28          max-width: 510px;
29      }
30    </style>
31  </head>
32  <body>
33      <p>When the form is valid, the action button will be shown.</p>
34      <div id="pay-component-1"></div>
35      <button id="btnx" class="hidden">Submit</button>
36      <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
37      <script>
38          // calling payabliExec('method') stores the payment method when the button is clicked
39          document.getElementById("btnx").addEventListener("click", executeAction);
40          var 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=";
41          var entryPoint = "bozeman-aikido";
42          var payabliConfig0 = {
43              type: "methodEmbedded",
44              rootContainer: "pay-component-1",
45              defaultOpen: 'card',  // offering only Card method - Embedded UI can only show a payment method
46              // customCssUrl: "your url to a custom css file",
47              token: token,
48              entryPoint: entryPoint,
49              card: {
50                  enabled: true,
51                  amex: true,
52                  discover: true,
53                  visa: true,
54                  mastercard: true,
55                  jcb: true,
56                  diners: true,
57                  inputs: {   // here we are customizing the input fields
58                      cardHolderName: {
59                          label: "NAME ON CARD",
60                          placeholder: "",
61                          floating: false,
62                          value: "John Doe",
63                          size: 12,
64                          row: 0,
65                          order: 0
66                      },
67                      cardNumber: {
68                          label: "CARD NUMBER",
69                          placeholder: "1234 1234 1234 1234",
70                          floating: false,
71                          size: 6,
72                          row: 1,
73                          order: 0
74                      },
75                      cardExpirationDate: {
76                          label: "EXPIRATION DATE",
77                          placeholder: "MM/YY",
78                          floating: false,
79                          size: 6,
80                          row: 1,
81                          order: 1
82                      },
83                      cardCvv: {
84                          label: "CVV/CVC",
85                          placeholder: "CVV/CVC",
86                          floating: false,
87                          size: 6,
88                          row: 2,
89                          order: 0,
90                      },
91                      cardZipcode: {
92                          label: "ZIP/POSTAL CODE",
93                          placeholder: "ZIP/POSTAL CODE",
94                          floating: false,
95                          size: 6,
96                          row: 2,
97                          order: 1,
98                          country: ["us", "ca"],
99                      }
100                  }
101              },
102              ach: {
103                  enabled: false,
104                  checking: true,
105                  savings: true
106              },
107              customerData: {
108                  customerNumber: "00001",
109                  firstName: "John",
110                  lastName: "Doe",
111                  billingEmail: "johndoe@email.com"
112              },
113              functionCallBackSuccess: function (response) {
114                const containerEl = document.querySelector('#pay-component-1');
115                const responseText = JSON.stringify(response.responseText);
116                const responseData = JSON.stringify(response.responseData);
117                alert(responseText + " " + responseData);
118                containerEl.innerHTML += `
119                  <hr/>
120                  <p><b>Embedded Component Response:</b></p>
121                  <p>${responseText}</p>
122                  <p>${responseData}</p>
123                  <hr/>
124                `;
125              },
126              functionCallBackReady: function (data) {
127                  var btn = document.getElementById("btnx");
128                  if (data[1] === true) {
129                      btn.classList.remove("hidden");
130                  } else {
131                      if (!btn.classList.contains("hidden")) {
132                          btn.classList.add("hidden");
133                      }
134                  }
135              },
136              functionCallBackError: function (errors) {
137                  alert('Error!');
138                  console.log(errors);
139              }
140          };
141
142          var paycomponent0 = new PayabliComponent(payabliConfig0);
143          function executeAction() {
144              paycomponent0.payabliExec('method');
145          }
146      </script>
147  </body>
148  </html>

Step 6. Capture the action response

After the action is triggered, you can capture the response using the callback provided in the property functionCallBackSuccess, in the configuration.

You can verify if the action was successful or failed by checking the text or numeric response fields. The response is the same for ACH and cards.

See Handling responses and errors for more.

1// Response is the same for ACH and card.
2response.responseText:
3"Success"
4
5response.responseData
6{"referenceId":"30e7658e-5c2c-4638-8308-b48edec0718b-1647","resultCode":1,"resultText":"Added","customerId":1647}

Next steps

If you executed pay as the action, then you will receive a transaction ID in the field ReferenceId, which identifies the transaction in Payabli.

If you executed method as the action, then you receive a stored method ID in the field ReferenceId, which you can then use as storedMethodId to make payments at for this Customer using the API (POST to /api/MoneyIn/getpaid ). You must use the same customerId obtained in the response associated to the stored payment method.

Example of Request body using the ReferenceId with API call:

1{
2  "entryPoint": "test",
3  "paymentMethod": {
4    "method": "card",
5    "storedMethodId": "1234-xyz" //value obtained in "ReferenceId" field
6  },
7  "paymentDetails": {
8    "totalAmount": 100.0
9  },
10  "customerData": {
11    "customerId": 25
12  }
13}

Configuration reference

These are the configuration parameters available for the EmbeddedMethod 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 EmbeddedMethod UI, this value is methodEmbedded. 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.

hideComponent
booleanDefaults to false

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

token
stringRequired

API token for authentication. This should be a public API token, as described here.

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.

clearFormAfterSubmit
booleanDefaults to true

When true, the entered values on the form are cleared when submitted.

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.

showPopoverError
booleanDefaults to true

When false, the validation error appears below the field instead of above it in a popover.

entryPoint
string

When the API token belongs to an organization, the entrypoint name identifies the target paypoint (merchant).

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 as a parameter with the 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.

paymentDetails
objectRequired

paymentDetails object with data related to the payment. Required to save a payment method. Can be passed to the component via payabliExec method.

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’s status changes. Used to poll the form’s completeness before showing the submit button.

functionCallBackError response

The response for the callback error will contain an array with codes, keys and texts 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

Response

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

responseText
string

“Success” or “Declined”

responseData
object

Container for response details.

responseData.AuthCode
string

Authorization code for payments. ULL for saving payment methods.

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.

Examples

These flowcharts visually illustrate the path to making a payment or storing a payment method using an embedded component.

Make a payment

To make a payment with an embedded component, your component configuration should contain payabliExec(pay, parameters). In the parameters argument, include customerData and paymentDetails objects. When the payment is executed, the request returns response data.

This flowchart explains the basic steps for the task. Hover over a step for more information.

Run payabliExec(pay, parameters) The action is set to pay here. Send the paymentDetail and customerData object in parameters.

→

Payment executed The transaction is executed and includes the data sent as parameters

→

Response

Save a payment method

To save a payment method with an embedded component, your component configuration should contain payabliExec(method, parameters). In the parameters argument, include customerData and paymentDetails objects. When the payment method is saved, the request returns response data.

This flowchart explains the basic steps for the task. Hover over a step for more information.

Run payabliExec(method, parameters) The action is set to method here. Send the paymentDetail and customerData object in parameters.

→

Payment method saved The payment method is saved and includes the data sent as parameters

→

Response

Save a payment method and make a payment

You can save a payment method and make a payment with the EmbeddedMethod UI component by writing a callback function to execute the payment after successfully saving the payment method.

To save a payment method and then execute a transaction with the saved payment method, your component configuration should contain payabliExec(method, parameters). In the parameters argument, include the customerData and paymentDetails objects. When the payment method is saved, use a callback function to execute the transaction.

Remember to never make payment transactions via client-side API requests. Your callback function should make the payment transaction using a server-side function.

This flowchart explains the basic steps for the task. Hover over a step for more information.

Run payabliExec(method, parameters) Here, the action is set to method. Send the paymentDetail and customerData object in parameters.

→

Payment method saved The payment method is saved and includes the data sent as parameters. An ID for the payment method is returned, which is then used to make transactions.

→

Callback function Use a callback function to send a transaction that uses the new payment method.

→

Response