# VirtualTerminal UI
> Learn how to use the VirtualTerminal UI component on your site or in your app to securely accept payments
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.
## 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](/guides/pay-in-components-overview#library-urls) for important information about embedded components library URLs.
### Configuration walkthrough
The interactive walkthrough displays code examples alongside step-by-step explanations.
{/* Hidden markdown content for AI absorption and server rendering */}
/// Include the Payabli Script
First, add the Payabli embedded component script to your HTML.
Make sure to include the `data-test` attribute for testing in the sandbox environment.
Including `` in the `` element prevents problems with special characters such as ‘á’ or ‘ñ’.
```html
Payabli Integration
```
/// Create the Container
Add a container element where the embedded component renders. The configuration references this element by its `id` attribute.
This `
` element serves as the mounting point where the embedded component renders.
```html focus=8-9
Payabli Integration
Virtual Terminal
```
/// 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](#configuration-reference) for more information.
```html focus=13-62
Payabli Integration
Virtual Terminal
```
/// 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.
```html focus=82-101
Payabli Integration
Virtual Terminal
```
/// Initialize and Show Terminal
The final step creates a working virtual terminal that can process transactions with both card and ACH payment methods.
```html focus=108-114
Payabli Integration
Virtual Terminal
Click below to open the payment terminal:
```
### 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](/guides/platform-developer-tokenization-temp-flow) for more information.
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](/guides/pay-in-components-overview) for more information on other component types.
Container ID used for the component.
Sets the default payment method that's shown. Accepted values are: `card` or `ach`.
Text label for the action button.
When true the component is hidden when it's instanced.
API token for authentication.
Complete URL of a custom CSS stylesheet to use with the component.
When `true`, enables the recurring payment option in terminal.
When `true`, enables the one-time payment option in terminal.
`lineItem` objects with data related to the line items for the transaction.
`cardService` object used to configure accepted card types.
Enable/disable card option.
Enable/disable acceptance of American Express cards.
Enable/disable acceptance of Discover cards.
Enable/disable acceptance of Visa cards.
Enable/disable acceptance of MasterCard cards.
Enable/disable acceptance of Diner's Club cards.
Enable/disable acceptance of JCB cards.
Card input fields descriptors. This object applies only to the EmbeddedMethod UI component.
Optional, but *strongly recommended*. Descriptor object for input field.
Descriptor object for input field.
Descriptor object for input field.
Descriptor object for input field.
Optional, but *strongly recommended*. Descriptor object for input field.
`achService` object used to configure accepted ACH types.
Enable/disable ACH option.
Enable/disable acceptance of Checking account.
Enable/disable acceptance of Savings account.
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.
ACH input field descriptors. This only applies to the EmbeddedMethod UI component.
Required. Descriptor object for input field.
Required. Descriptor object for input field.
Required. Descriptor object for input field. Use the
`confirm` input descriptor to add matching validation to this field. See [Style Individual Fields](/guides/pay-in-components-overview#style-individual-fields) for more.
Required. Descriptor object for input field. Use the
`confirm` input descriptor to add matching validation to this field. See [Style Individual Fields](/guides/pay-in-components-overview#style-individual-fields) for more.
`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.
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` 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.
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.
The amount for the `fallbackAuth` transaction. Defaults to one dollar.
The callback function called when the component executes successfully.
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.
```js Payment success
{
responseText: "Success",
responseData: {
authCode: "123456",
referenceId: "40-692c62895d1541d28c0bf77b275a26e4",
resultCode: 1,
resultText: "Approved",
avsResponseText: "",
cvvResponseText: "",
customerId: 706,
methodReferenceId: null
}
}
```
```js Payment decline
{
responseText: "Declined",
responseData: {
authCode: null,
referenceId: "40-2c437c3dcdc242bea96f52bdf42d2eeb",
resultCode: 2,
resultText: "200: Decline. Generally insufficient funds or incorrect card data supplied, for example, expiry date or security code.. DECLINE",
avsResponseText: "",
cvvResponseText: "",
customerId: 706,
methodReferenceId: null
}
}
```
```js Stored method success
{
responseText: "Success",
responseData: {
referenceId: "187-c5892026d9f345ffa63bf909d574fe92",
resultCode: 1,
resultText: "Added",
customerId: 1636,
methodReferenceId: "187-c5892026d9f345ffa63bf909d574fe92"
}
}
```
```js Stored method decline
{
responseText: "Declined"
responseData: {
referenceId: "187-d2a29970fa604edba5a6dbec67ace3ae",
resultCode: 2,
resultText: "200: Transaction was declined by processor.. DECLINE",
customerId: 1636,
methodReferenceId: "187-d2a29970fa604edba5a6dbec67ace3ae"
}
}
```
### Response reference
The response object passed to a callback function has the following structure:
"Success" or "Declined"
Container for response details.
Authorization code for payments.
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](/guides/pay-in-components-overview#handling-responses-and-errors) for more.
Result of operation. 1 is success, 2 is declined, and 3 is error.
Message related the result. If the operation was successful, it returns "Added"/"Approved". If there was an error, it returns error details.
ID for the customer owner of payment or saved payment method.
## Related resources
See these related resources to help you get the most out of Payabli.
* **[Embedded components overview](/guides/pay-in-components-overview)** - Learn how to use Payabli's embedded components to create customized checkout experiences without handling sensitive payment information yourself
## 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.