VirtualTerminal UI

Applies to:Developers

The VirtualTerminal UI component lets you embed a payment terminal inside your website or application. This modal-based component is perfect for admin interfaces, customer service tools, and any application where you need to process payments on behalf of customers.

an image of a virtual terminal component window

Usage

This component lets you add a robust virtual terminal tool to your pages or apps. Follow the configuration walkthrough to set it up in your project.

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

Configuration walkthrough

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

Loading walkthrough content

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>Virtual Terminal</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.

-62

1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta charset="UTF-8">
5   <title>Payabli Integration</title>
6 </head>
7 <body>
8   <h1>Virtual Terminal</h1>
9   <div id="pay-component-1"></div>
10   <button id="show-btn">Show Terminal</button>
11   
12   <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
13   <script>
14     const payabliConfig = {
15       type: "vterminal",
16       rootContainer: "pay-component-1",
17       token: "your-public-api-token",
18       entryPoint: "your-entry-point",
19       buttonLabelInModal: "Review & Pay",
20       hideComponent: true,
21       oneTimePayment: true,
22       recurringPayment: true,
23       defaultOpen: "card",
24       card: {
25         enabled: true,
26         amex: true,
27         discover: true,
28         visa: true,
29         mastercard: true,
30         jcb: true,
31         diners: true,
32         fallbackAuth: true
33       },
34       ach: {
35         enabled: true,
36         checking: true,
37         savings: true
38       },
39       customerData: {
40         customerId: 13
41       },
42       lineItems: [
43         {
44           name: "Widgets",
45           type: "customer",
46           label: "Widgets",
47           value: "150.00",
48           description: "Premium widget package",
49           quantity: 1,
50           showDescription: false
51         },
52         {
53           name: "Gadgets",
54           type: "quantity",
55           label: "Gadgets",
56           value: "75.00",
57           description: "Essential gadget collection",
58           quantity: 2,
59           showDescription: false
60         }
61       ]
62     };
63   </script>
64 </body>
65 </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.

-101

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     #response-display {
18       margin-top: 20px;
19       padding: 16px;
20       border-radius: 6px;
21       background: #f8fafc;
22       border: 1px solid #e2e8f0;
23     }
24   </style>
25 </head>
26 <body>
27   <h1>Virtual Terminal</h1>
28   <div id="pay-component-1"></div>
29   <button id="show-btn">Show Terminal</button>
30   <div id="response-display"></div>
31   
32   <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
33   <script>
34     const payabliConfig = {
35       type: "vterminal",
36       rootContainer: "pay-component-1",
37       token: "your-public-api-token",
38       entryPoint: "your-entry-point",
39       buttonLabelInModal: "Review & Pay",
40       hideComponent: true,
41       oneTimePayment: true,
42       recurringPayment: true,
43       defaultOpen: "card",
44       card: {
45         enabled: true,
46         amex: true,
47         discover: true,
48         visa: true,
49         mastercard: true,
50         jcb: true,
51         diners: true,
52         fallbackAuth: true
53       },
54       ach: {
55         enabled: true,
56         checking: true,
57         savings: true
58       },
59       customerData: {
60         customerId: 13
61       },
62       lineItems: [
63         {
64           name: "Widgets",
65           type: "customer",
66           label: "Widgets",
67           value: "150.00",
68           description: "Premium widget package",
69           quantity: 1,
70           showDescription: false
71         },
72         {
73           name: "Gadgets",
74           type: "quantity",
75           label: "Gadgets",
76           value: "75.00",
77           description: "Essential gadget collection",
78           quantity: 2,
79           showDescription: false
80         }
81       ],
82       functionCallBackSuccess: function(referenceId) {
83         console.log("Payment successful:", referenceId);
84         document.getElementById("response-display").innerHTML += `
85           <hr/>
86           <p><strong>Payment Successful!</strong></p>
87           <p>Reference ID: ${referenceId}</p>
88           <p>Transaction processed successfully.</p>
89           <hr/>
90         `;
91       },
92       functionCallBackError: function(error) {
93         console.error("Payment error:", error);
94         document.getElementById("response-display").innerHTML += `
95           <hr/>
96           <p><strong>Payment Error</strong></p>
97           <p>Payment processing failed. Please try again.</p>
98           <hr/>
99         `;
100       }
101     };
102   </script>
103 </body>
104 </html>

/// Initialize and Show Terminal

The final step creates a working virtual terminal that can process transactions with both card and ACH payment methods.

-114

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     #response-display {
18       margin-top: 20px;
19       padding: 16px;
20       border-radius: 6px;
21       background: #f8fafc;
22       border: 1px solid #e2e8f0;
23     }
24     #pay-component-1 {
25       max-width: 610px;
26       margin: 20px 0;
27     }
28   </style>
29 </head>
30 <body>
31   <h1>Virtual Terminal</h1>
32   <p>Click below to open the payment terminal:</p>
33   <div id="pay-component-1"></div>
34   <button id="show-btn">Show Terminal</button>
35   <div id="response-display"></div>
36   
37   <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
38   <script>
39     const payabliConfig = {
40       type: "vterminal",
41       rootContainer: "pay-component-1",
42       token: "your-public-api-token",
43       entryPoint: "your-entry-point",
44       buttonLabelInModal: "Review & Pay",
45       hideComponent: true,
46       oneTimePayment: true,
47       recurringPayment: true,
48       defaultOpen: "card",
49       card: {
50         enabled: true,
51         amex: true,
52         discover: true,
53         visa: true,
54         mastercard: true,
55         jcb: true,
56         diners: true,
57         fallbackAuth: true
58       },
59       ach: {
60         enabled: true,
61         checking: true,
62         savings: true
63       },
64       customerData: {
65         customerId: 13
66       },
67       lineItems: [
68         {
69           name: "Widgets",
70           type: "customer",
71           label: "Widgets",
72           value: "150.00",
73           description: "Premium widget package",
74           quantity: 1,
75           showDescription: false
76         },
77         {
78           name: "Gadgets",
79           type: "quantity",
80           label: "Gadgets",
81           value: "75.00",
82           description: "Essential gadget collection",
83           quantity: 2,
84           showDescription: false
85         }
86       ],
87       functionCallBackSuccess: function(referenceId) {
88         console.log("Payment successful:", referenceId);
89         document.getElementById("response-display").innerHTML += `
90           <hr/>
91           <p><strong>Payment Successful!</strong></p>
92           <p>Reference ID: ${referenceId}</p>
93           <p>Transaction processed successfully.</p>
94           <hr/>
95         `;
96       },
97       functionCallBackError: function(error) {
98         console.error("Payment error:", error);
99         document.getElementById("response-display").innerHTML += `
100           <hr/>
101           <p><strong>Payment Error</strong></p>
102           <p>Payment processing failed. Please try again.</p>
103           <hr/>
104         `;
105       }
106     };
107 
108     // Initialize the virtual terminal
109     const virtualTerminal = new PayabliComponent(payabliConfig);
110     
111     // Add click handler to show the terminal modal
112     document.getElementById("show-btn").addEventListener("click", function() {
113       virtualTerminal.showModal();
114     });
115   </script>
116 </body>
117 </html>

Configuration reference

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

customCssUrl

string

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

recurringPayment

boolean

When true, enables the recurring payment option in terminal.

oneTimePayment

boolean

When true, enables the one-time payment option in terminal.

lineItems

array of objects

lineItem objects with data related to the line items for the transaction.

card

objectRequired

cardService object used to configure accepted card types.

properties

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.

properties

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.

properties

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.

properties

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.

paymentDetails

objectRequired

paymentDetails object with data related to the payment. Required when running a payment. Can be passed to the component via payabliExec method. See paymentDetails Object for a full reference.

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     authCode: "123456",
5     referenceId: "40-692c62895d1541d28c0bf77b275a26e4",
6     resultCode: 1,
7     resultText: "Approved",
8     avsResponseText: "",
9     cvvResponseText: "",
10     customerId: 706,
11     methodReferenceId: null
12   }
13 }

Response reference

The response object passed to a callback function has the following structure:

responseText

string

“Success” or “Declined”

responseData

object

Container for response details.

properties

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