Pay InEmbedded components

ExpressCheckout UI

Learn how to use the ExpressCheckout UI component on your site or in your app to securely accept digital wallet payments

Applies to:Developers

The ExpressCheckout component lets you embed an express checkout for digital wallets inside your website or application.

an image of an ExpressCheckout component rendered on a site

Usage

This component lets you add a robust low-code way to accept payments from a digital wallet to your pages or apps.

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-2"></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 reference of options.

Full configuration example
1<!DOCTYPE html>
2<html>
3<head>
4  <meta charset="UTF-8">
5</head>
6<body>
7  <div id="express-checkout-component"></div>
8  <script type="text/javascript" src="https://embedded-component-sandbox.payabli.com/component.js">
9    //Use the correct version for your environment
10  </script>
11  <script>
12    var token = ""; // Input your Public Organization API Token here:
13    var entryPoint = ""; // Input your paypoint entryName here:
14    var expressCheckoutConfig = {
15      token: token,
16      type: "expressCheckout",
17      entryPoint: entryPoint,
18      rootContainer: "express-checkout-component",
19      //customCssUrl: "your url to a custom css file",
20      expressCheckout: {
21        amount: 100,
22        fee: 0.01,
23        currency: "USD",
24        supportedNetworks: ["visa"],
25        columns: 1,
26        applePay: {
27          enabled: true,
28          buttonStyle: "black-outline",
29          buttonType: "plain",
30          language: "en-US",
31        },
32        requiredShippingContactFields: true,
33        appearance: {
34          buttonHeight: 50, // optional
35          buttonBorderRadius: 10, // optional
36          padding: {
37            x: 10, // optional
38            y: 10, // optional
39          },
40        },
41      },
42      customerData: {
43        customerNumber: "00001",
44        firstName: "John",
45        lastName: "Doe",
46        billingEmail: "johndoe@email.com"
47      },
48      functionCallBackReady: function(data) {
49        console.log('Apple Pay ready: ', data)
50      },
51      functionCallBackSuccess: function(data) {
52        console.log('Apple Pay Success: ', data)
53      },
54      functionCallBackError: function(data) {
55        console.log('Apple Pay Error: ', data)
56      },
57      functionCallBackCancel: function(data) {
58        console.log('Apple Pay Cancel: ', data)
59      },
60    }
61    new PayabliComponent(payabliConfig0);
62  </script>
63</body>
64</html>

Step 4: Style the component

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

Configuration reference

These are the configuration parameters available for the ExpressCheckout 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 ExpressCheckout UI, this value is expressCheckout. See the Embedded Components Overview for more information on other component types.

rootContainer
stringRequired

Container ID used for the component.

token
stringRequired

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

entryPoint
stringRequired

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

customCssUrl
string

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

expressCheckout
objectRequired

Configuration for the express checkout functionality.

amount
numberRequired

The amount for the transaction.

fee
numberRequired

The fee for the transaction.

currency
stringRequired

The currency for the transaction.

columns
objectDefaults to 1

Define the number of columns to use for digital wallet display.

supportedNetworks
string[]Required

Card networks to accept payments from. Suggested options:

  • amex
  • visa
  • discover
  • masterCard
  • jcb
applePay
objectRequired
enabled
booleanRequired

When true, Apple Pay is enabled.

buttonStyle
enumDefaults to black

The Apple Pay button style. Supported options:

  • “black”: Default black button.
  • “white-outline”: White button with an outline.
  • “white”: Solid white button.
buttonType
enumDefaults to plain

The text on Apple Pay button. Supported options:

Button TypeDescriptionText on Apple Pay Button
"plain"An Apple Pay button with the Apple Pay logo only, useful when an additional call to action isn’t needed.Apple Pay logo only (no text)
"buy"Use this button for product purchases.Buy with Apple Pay logo
"donate"Used by approved nonprofits. Lets people make donations.Donate with Apple Pay logo
"check-out"Use this button for purchase experiences that include other payment buttons that start with “Check out”.Check Out with Apple Pay logo
"book"Use this button for booking appointments, flights, or other experiences.Book with Apple Pay logo
"continue"Use this button for general purchases.Continue with Apple Pay logo
"top-up"Use this button for adding money to an account, or payment system.Top Up with Apple Pay logo
"order"Use this button for placing orders for items.Order with Apple Pay logo
"rent"Use this button for renting items such as equipment or cars.Rent with Apple Pay logo
"support"Use this button for helping people give money to projects, causes, organizations, and other entities.Support with Apple Pay logo
"contribute"Use this button to help people give money to projects, causes, organizations, and other entities.Contribute with Apple Pay logo
"tip"Use this button to let people tip for goods or services.Tip with Apple Pay logo
"pay"Use this button for general purchases.Pay with Apple Pay logo
language
enumDefaults to en-us

The Apple Pay button locale. Supported options:

  • en-US: English (US)
  • ar-AB: Arabic
  • ca-ES: Catalan
  • zh-CN: Chinese (China)
  • zh-HK: Chinese (Hong Kong)
  • zh-TW: Chinese (Taiwan)
  • hr-HR: Croatian
  • cs-CZ: Czech
  • da-DK: Danish
  • de-DE: German
  • nl-NL: Dutch
  • en-AU: English (Australia)
  • en-GB: English (UK)
  • fi-FI: Finnish
  • fr-CA: French (Canada)
  • fr-FR: French (France)
  • el-GR: Greek
  • he-IL: Hebrew
  • hi-IN: Hindi
  • hu-HU: Hungarian
  • id-ID: Indonesian
  • it-IT: Italian
  • ja-JP: Japanese
  • ko-KR: Korean
  • ms-MY: Malay
  • nb-NO: Norwegian
  • pl-PL: Polish
  • pt-BR: Portuguese (Brazil)
  • pt-PT: Portuguese (Portugal)
  • ro-RO: Romanian
  • ru-RU: Russian
  • sk-SK: Slovak
  • es-MX: Spanish (Mexico)
  • es-ES: Spanish (Spain)
  • sv-SE: Swedish
  • th-TH: Thai
  • tr-TR: Turkish
  • uk-UA: Ukrainian
  • vi-VN: Vietnamese
requiredShippingContactFields
boolean

When this field is true, the following fields ["postalAddress", "name", "phoneticName", "phone", "email"] are required. They will be sent with the payment and can be read through the callbacks.

appearance
object
buttonHeight
numberDefaults to 44

Height of the button.

buttonBorderRadius
numberDefaults to 4

Border radius of the button.

padding
object
x
numberDefaults to 8

Horizontal padding.

y
numberDefaults to 11

Vertical padding.

customerData
objectRequired
customerNumber
stringRequired

Customer’s identification number.

firstName
stringRequired

Customer’s first name.

lastName
stringRequired

Customer’s last name.

billingEmail
stringRequired

Customer’s billing email address.

functionCallBackReady
function

Triggered when the ExpressCheckout component is ready to use.

functionCallBackSuccess
function

Triggered upon successful completion of a digital wallet transaction.

functionCallBackError
function

Triggered if an error occurs during the digital wallet transaction.

functionCallBackCancel
function

Triggered if the user cancels the digital wallet transaction.

Response examples

functionCallbackReady response

This response is triggered when the component is ready to use.

1  {
2    applePay: true,
3    googlePay: false
4  }
applePay
boolean

When true, the component is ready to accept Apple Pay.

googlePay
boolean

Not in use yet.

functionCallbackSuccess response

When a transaction is successfully completed via the ExpressCheckout component, the functionCallBackSuccess response is triggered.

In the response, the referenceId is the transaction ID you can use for other operations.

1{
2    "data": {
3        "isSuccess": true,
4        "pageIdentifier": "t.XMzKRgtV6eJrI2Fsn45RLKuRujHi53qDnsizyJXNM7ChdejoRNOdb0Dm7VXQ3H/aBVMu+14IB9sOS1hbZF/kXMKgUY94nspVI+mRSphe8HeSwbr5OxLUSmu0Uuc6RmDzaLUYXn8eDr…",
5        "responseData": {
6            "authCode": "",
7            "avsResponseText": null,
8            "billingContact": {
9                "addressLines": [
10                    "9425 SW 172nd Pl"
11                ],
12                "administrativeArea": "FL",
13                "country": "United States",
14                "countryCode": "US",
15                "familyName": "Martinez",
16                "givenName": "Fernando",
17                "locality": "Miami",
18                "phoneticFamilyName": "",
19                "phoneticGivenName": "",
20                "postalCode": "33197",
21                "subAdministrativeArea": "",
22                "subLocality": ""
23            },
24            "customerId": 6886,
25            "cvvResponseText": null,
26            "methodReferenceId": null,
27            "referenceId": "1148-2305e2cb80eb5969920f2cf9f2565455",
28            "resultCode": 1,
29            "resultText": "Approved",
30            "shippingContact": {
31                "addressLines": [
32                    "9425 SW 172nd Pl"
33                ],
34                "administrativeArea": "FL",
35                "country": "United States",
36                "countryCode": "US",
37                "emailAddress": "fernandotest@payabli.com",
38                "familyName": "Martinez",
39                "givenName": "Fernando",
40                "locality": "Miami",
41                "phoneNumber": "4089752020",
42                "phoneticFamilyName": "4192412942195",
43                "phoneticGivenName": "941924129412943",
44                "postalCode": "33197",
45                "subAdministrativeArea": "",
46                "subLocality": ""
47            }
48        },
49        "responseText": "Success"
50    },
51    "paymentMethod": "apple_pay"
52}
responseText
string

“Success” or “Declined”

responseData
object

Container for response details.

responseData.authCode
string

Authorization code for payments.

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.

responseData.avsResponseText
string

Text code describing the result for address validation.

responseData.cvvResponseText
string

Text code describing the result for CVV validation.

responseData.methodReferenceId
string

The stored method’s identifier (sometimes referred to as ‘token’) in Payabli. When null, the method wasn’t created, or doesn’t exist, depending on the operation performed.

responseData.billingContact
object

The billing contact information.

addressLines
array

The street portion of the address for the contact. For example: 123 Main Street.

administrativeArea
string

The contact’s state. For example, CA.

country
string

Billing country.

countryCode
string

The contact’s ISO 3166 country code.

emailAddress
string

The contact’s email address.

familyName
string

The contact’s family name, also known as last name.

givenName
string

The contact’s given name, also known as first name.

locality
string

The contact’s city. For example, Los Angeles.

phoneticFamilyName
string

Specifies the pronunciation of the contact’s last name.

phoneticGivenName
string

Specifies the pronunciation of the contact’s first name.

postalCode
string

The contact’s postal code.

subAdministrativeArea
string

The contact’s county or other region.

subLocality
string

Additional information associated with the contact’s address.

responseData.shippingContact
object

Shipping address and contact information for the transaction.

addressLines
array

The street portion of the address for the contact. For example: 123 Main Street.

administrativeArea
string

The contact’s state. For example, CA.

country
string

Billing country.

countryCode
string

The contact’s ISO 3166 country code.

emailAddress
string

The contact’s email address.

familyName
string

The contact’s family name, also known as last name.

givenName
string

The contact’s given name, also known as first name.

locality
string

The contact’s city. For example, Los Angeles.

phoneNumber
string

The contact’s phone number.

phoneticFamilyName
string

Specifies the pronunciation of the contact’s last name.

phoneticGivenName
string

Specifies the pronunciation of the contact’s first name.

postalCode
string

The contact’s postal code.

subAdministrativeArea
string

The contact’s county or other region.

subLocality
string

Additional information associated with the contact’s address.

isSuccess
boolean

Boolean indicating whether the operation was successful. A true value indicates success. A false value indicates failure.

pageIdentifier
string

Auxiliary validation used by Payabli in payment pages and components.

paymentMethod
string

The payment method used. Possible values include “apple_pay”, “google_pay”, etc.

functionCallBackError response

This response is triggered if an error occurs during the transaction.

1{
2  "paymentMethod": "apple_pay", // apple_pay, google_pay etc
3  "error": {
4    "isSuccess": false
5    "pageIdentifier": null,
6    "responseCode": 5005,
7    "responseData": {
8      "explanation": string,
9      "todoAction": string
10    },
11    "responseText": string,
12    roomId: null
13  }
14}
paymentMethod
string

The payment method used. Possible values include “apple_pay”, “google_pay”, etc.

error
object

Container for error details when an error occurs.

isSuccess
boolean

Indicates whether the operation was successful. In error cases, this will be false.

pageIdentifier
string

Auxiliary validation used by Payabli in payment pages and components.

responseCode
number

The error code. For example, 5005. See API responseCode and resultCode Reference for a full list of error codes.

responseData
object

Additional details about the error.

explanation
string

A detailed explanation of the error.

todoAction
string

Suggested action to resolve the error.

responseText
string

A brief description of the error.

roomId
number

Internal field used by Payabli.

functionCallBackCancel response

This response is triggered when the user cancels the transaction while the modal is shown.

1{
2  data: {
3    isTrusted: true
4  },
5  paymentMethod: "apple_pay"
6}
data
object

Container for response data.

isTrusted
boolean

In this field, true indicates that the event was triggered by a user action, such as a user manually canceling the payment process.

paymentMethod
string

The digital wallet method used. Currently, only apple_pay is supported.

Combine components

If you want to accept digital wallet payments along with card or ACH payments, you can load both the EmbeddedMethod UI and ExpressCheckout UI components on the same webpage. You can also use updateConfig to switch between component configurations on your page.

The code example renders the components in this image:

an image of an ExpressCheckout component rendered on a site
ExpressCheckout, ACH, and Card example
1<body>
2    <div>
3        <div id="embeddedComponentStyle">
4            <h4>Pay your order</h4>
5            <div id='containerExpressCheckout' class="hidden">
6                <div id='express-checkout-component'></div>
7                <div style='display: flex; gap: 0.5rem; align-items:center' class="my-2">
8                    <hr style='height:1px;width:35%' />
9                    <small style='width:100%; text-align: center'>or pay with card or bank account</small>
10                    <hr style='height:1px;width:35%' />
11                </div>
12
13            </div>
14            <div class="tabs">
15                <ul class="nav nav-tabs" id="tabs" role="tablist">
16                    <li class="nav-item" role="presentation">
17                        <a class="nav-link active" id="card-tab" data-bs-toggle="tab"
18                            data-bs-target="#pay-component-card-cont" role="tab" aria-controls="pay-component-card-cont"
19                            aria-selected="true">Payment Card</a>
20                    </li>
21                    <li class="nav-item" role="presentation">
22                        <a class="nav-link" id="bank-tab" data-bs-toggle="tab" data-bs-target="#pay-component-ach-cont"
23                            role="tab" aria-controls="pay-component-ach-cont" aria-selected="false">Bank Debit</a>
24                    </li>
25                </ul>
26            </div>
27            <div class="payment-form tab-content">
28                <div class="tab-pane fade show active" id="pay-component-card-cont" role="tabpanel"
29                    aria-labelledby="pay-component-card-cont">
30                    <div id="pay-component-card">
31
32                    </div>
33                    <button id="btn-pay" class="mt-20">
34                        <img
35                            src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAAXNSR0IArs4c6QAAAPxJREFUSEvtldGNwjAMhr9/AnQTAJNwbMAG9CZATAC3ARvABjACN8mVDW4DI6Mg9VqStEWVeMAvjSrb3x8ndsTApoHz0wpgZgtgBXwGQWfgW5J/k5YFmNkBWEayOGSbIiQBQfkxJFgDp7AugE1Yz1M7yQG8BDNgLWlXVWpmrtwhP5LupWtsJgewEPEh6a8GmAC//k9SNE8rQCyBmd0EDAbI3aAbPOXURmEO0gCYmR/YHvAad7ES+KrfqEcAdxx3yVzxLSVNq7GPAPeb04tRP/A3oNm5taZ7l+g1S+RTc9SrCeAi6d8EiI0Kf8W6dvMFKLKjoqfyaFj2TX4WeAX0MmsZ8nx06AAAAABJRU5ErkJggg==" />
36                        Save Payment
37                    </button>
38                </div>
39            </div>
40        </div>
41    </div>
42
43    <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test>>"></script>
44
45    <script>
46        var token =
47            "<API TOKEN";
48        var entryPoint = "7f1a381696";
49        var customCssUrl = "https://embedded-component-sandbox.payabli.com/customForm.css";
50        var payabliConfigCard = { // The config for the EmbeddedMethodUI component that accepts ACH
51            type: "methodEmbedded",
52            rootContainer: "pay-component-card",
53            defaultOpen: "card",
54            token: token,
55            customCssUrl: customCssUrl,
56            entryPoint: entryPoint,
57            card: {
58                enabled: true,
59                amex: false,
60                discover: true,
61                visa: true,
62                mastercard: true,
63                inputs: {
64                    //here we are customizing the input fields
65                    cardHolderName: {
66                        label: "NAME ON CARD",
67                        placeholder: "",
68                        floating: false,
69                        value: "John Doe",
70                        size: 12,
71                        row: 0,
72                        order: 0
73                    },
74                    cardNumber: {
75                        label: "CARD NUMBER",
76                        placeholder: "1234 1234 1234 1234",
77                        floating: false,
78                        size: 6,
79                        row: 1,
80                        order: 0
81                    },
82                    cardExpirationDate: {
83                        label: "EXPIRATION DATE",
84                        placeholder: "MM/YY",
85                        floating: false,
86                        size: 6,
87                        row: 1,
88                        order: 1
89                    },
90                    cardCvv: {
91                        label: "CVV/CVC",
92                        placeholder: "CVV/CVC",
93                        floating: false,
94                        size: 6,
95                        row: 2,
96                        order: 0
97                    },
98                    cardZipcode: {
99                        label: "ZIP/POSTAL CODE",
100                        placeholder: "Zip/Postal Code",
101                        floating: false,
102                        size: 6,
103                        row: 2,
104                        order: 1,
105                        country: ["us", "ca"],
106                    }
107                }
108            },
109            ach: {
110                enabled: false
111            },
112            customerData: {
113                customerNumber: "00001",
114                firstName: "John",
115                lastName: "Doeee",
116                billingEmail: "johndoe@email.com"
117            },
118            functionCallBackSuccess: function (response) {
119                alert("card success");
120                // paycomponentCard.removeListener();
121                paycomponentCard.payabliExec("reinit");
122            },
123            functionCallBackReady: function (data) { },
124            functionCallBackError: function (errors) {
125                alert("Error!");
126                console.log(errors);
127            }
128        };
129
130        var payabliConfigACH = { // The config for the EmbeddedMethodUI component that accepts ACH
131            type: "methodEmbedded",
132            entryPoint: entryPoint,
133            rootContainer: "pay-component-card",
134            defaultOpen: "ach",
135            token: token,
136            customCssUrl: customCssUrl,
137            customerData: {
138                customerNumber: "00001",
139                firstName: "John",
140                lastName: "Doe",
141                billingEmail: "johndoe@email.com"
142            },
143            card: {
144                enabled: false
145            },
146            ach: {
147                enabled: true,
148                checking: true,
149                savings: true,
150                inputs: {
151                    achAccountHolderName: {
152                        label: "ACCOUNTHOLDER NAME",
153                        floating: false,
154                        size: 6,
155                        row: 0,
156                        order: 0
157                    },
158                    achAccountType: {
159                        label: "ACCOUNT TYPE",
160                        floating: false,
161                        size: 6,
162                        row: 0,
163                        order: 1
164                    },
165                    achRouting: {
166                        label: "ROUTING NUMBER",
167                        floating: false,
168                        size: 6,
169                        row: 1,
170                        order: 0,
171                        confirm: true // Confirm routing number
172                    },
173                    achAccount: {
174                        label: "ACCOUNT NUMBER",
175                        floating: false,
176                        size: 6,
177                        row: 1,
178                        order: 1,
179                        confirm: true // Confirm account number
180                    }
181                }
182            },
183
184
185            functionCallBackSuccess: function (response) {
186                alert("ach");
187                // paycomponentCard.payabliExec('reinit');
188            },
189            functionCallBackError: function (errors) {
190                console.log(errors);
191            },
192            functionCallBackReady: function (data) {
193
194            }
195        };
196
197        var expressCheckoutConfig = { //The ExpressCheckout config
198            token: token,
199            type: "expressCheckout",
200            entryPoint: entryPoint,
201            rootContainer: "express-checkout-component",
202            //customCssUrl: "your url to a custom css file",
203            expressCheckout: {
204                amount: 100,
205                fee: 0.01,
206                currency: "USD",
207                supportedNetworks: ["visa"],
208                columns: 1,
209                applePay: {
210                    enabled: true,
211                    buttonStyle: "black-outline",
212                    buttonType: "plain",
213                    language: "en-US",
214                },
215                requiredShippingContactFields: true,
216                appearance: {
217                    buttonHeight: 50, // optional
218                    buttonBorderRadius: 10, // optional
219                    padding: {
220                        x: 10, // optional
221                        y: 10, // optional
222                    },
223                },
224            },
225            customerData: {
226                customerNumber: "00001",
227                firstName: "John",
228                lastName: "Doe",
229                billingEmail: "johndoe@email.com"
230            },
231            functionCallBackReady: function (data) {
232                console.log('Express Checkout ready: ', data)
233                const container = document.querySelector("#containerExpressCheckout");
234                console.log(container)
235                container.classList.remove("hidden");
236            },
237            functionCallBackSuccess: function (data) {
238                console.log('Express Checkout Success: ', data)
239            },
240            functionCallBackError: function (data) {
241                console.log('Express Checkout Error: ', data)
242            },
243            functionCallBackCancel: function (data) {
244                console.log('Express Checkout Cancel: ', data)
245            },
246        }
247        var paycomponentCard = new PayabliComponent(payabliConfigCard);
248
249        new PayabliComponent(expressCheckoutConfig)
250
251        function executeActionCard() {
252            paycomponentCard.payabliExec("pay", {
253                paymentDetails: {
254                    totalAmount: 100,
255                    serviceFee: 0,
256                    categories: [
257                        {
258                            label: "payment",
259                            amount: 100,
260                            qty: 1
261                        }
262                    ]
263                }
264            });
265        }
266
267        let cardTab = document.getElementById("card-tab");
268        let bankTab = document.getElementById("bank-tab");
269        let payBtn = document.getElementById("btn-pay");
270
271        cardTab.addEventListener("click", function () { // using updateConfig to switch between components
272            paycomponentCard.updateConfig(payabliConfigCard);
273        });
274
275        bankTab.addEventListener("click", function () {
276            paycomponentCard.updateConfig(payabliConfigACH);
277        });
278
279        payBtn.addEventListener("click", () => {
280            paycomponentCard.payabliExec("pay", {
281                paymentDetails: {
282                    totalAmount: 100,
283                    serviceFee: 0,
284                    categories: [
285                        {
286                            label: "payment",
287                            amount: 100,
288                            qty: 1
289                        }
290                    ]
291                }
292            });
293        });
294
295    </script>
296
297    </script>
298</body>
299</html>