VirtualTerminal UI

The VirtualTerminal UI component lets you embed a payment terminal inside your website or application.

Usage

This component lets you add a robust virtual terminal tool 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

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
</head>
<body>
    <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
</body>
</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

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
</head>
<body>
    <div id="pay-component-2"></div>
    <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
</body>
</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.

Expand for full configuration example

Full configuration example

  <!DOCTYPE html>
  <html>
  <head>
    <meta charset="UTF-8">
    <style>
      #pay-component-2 iframe{
        border: solid 1px transparent;
        max-width: 610px;
      }
    </style>
  </head>
      <body>
        <button id="btnx"> Click here to show the component</button>
        <div id="pay-component-2"></div>
        <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
        <script>
            document.getElementById('btnx').addEventListener('click', btnVT);
            var payabliConfig2 = {
                type: "vterminal",
                rootContainer: "pay-component-2",
                buttonLabelInModal: 'Review & Pay',
                oneTimePayment: true,
                entryPoint: "bozeman-aikido",
                recurringPayment: true,
                defaultOpen: 'ach',
                hideComponent: true,
                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=",
                card: {
                    enabled: true,
                    amex: true,
                    discover: true,
                    visa: true,
                    mastercard: true,
                    jcb: true, 
                    diners: true,
                    fallbackAuth: true,
                },
                ach: {
                    enabled: true,
                    checking: true,
                    savings: true
                },
                customerData: {
                    customerId: 13
                },
                functionCallBackSuccess: function (referenceId) {
                    alert(referenceId + ' done!!!');
                },
                functionCallBackError: function () {
                    alert('Error');
                },
                lineItems: [{
                    name: 'Widgets',
                    type: 'customer',
                    label: 'Widgets',
                    value: '150.00',
                    description: '',
                    quantity: 1,
                    showDescription: false
                },
                {
                    name: 'Gadgets',
                    type: 'quantity',
                    label: 'Gadgets',
                    value: '2340.00',
                    description: '',
                    quantity: 2,
                    showDescription: false
                }
                ]

            };
            var paycomponent2 = new PayabliComponent(payabliConfig2);

            function btnVT() {
              paycomponent2.showModal();
            }
        </script>
      </body>
  </html>

Response examples

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

// Response is the same for ACH and card. 
response.responseText: 
"Success"

response.responseData:
{"authCode":"123456","referenceId":"187-c5892026d9f345ffa63bf909d574fe92","resultCode":1,"resultText":"Approved","avsResponseText":"","cvvResponseText":"","customerId":1636}

Configuration reference

These are the configuration parameters available for the VirtualTerminal 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

string

required

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

string

required

Container ID used for the component.

defaultOpen

string

Sets the default payment method that’s shown. Accepted values are: card or ach.

Text label for the action button.

hideComponent

boolean

default:"false"

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

token

string

required

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. See lineItem object model for a full reference.

card

object

required

cardService object used to configure accepted card types.

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

Show properties

cardHolderName

object

Optional, but strongly recommended. Descriptor object for input field.

cardNumber

object

required

Descriptor object for input field.

cardExpirationDate

object

required

Descriptor object for input field.

cardCvv

object

required

Descriptor object for input field.

cardZipcode

object

Optional, but strongly recommended. Descriptor object for input field.

ach

object

required

achService object used to configure accepted ACH types.

Show properties

enabled

boolean

Enable/disable ACH option.

checking

boolean

Enable/disable acceptance of Checking account.

savings

boolean

Enable/disable acceptance of Savings account.

inputs

object

ACH input field descriptors. This only applies to the EmbeddedMethod UI component.

Show properties

achAccountHolderName

object

required

Required. Descriptor object for input field.

achAccountType

object

required

Required. Descriptor object for input field.

achRouting

object

required

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

object

required

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

object

required

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. See paymentMethod Object for a full reference.

customerData

object

required

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. See customerData (payorData) Object for a full reference.

paymentDetails

object

required

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

default:"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

integer | null

default:"100"

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 object

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

responseText

string

“Success” or “Declined”

responseData

object

Container for response details.

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

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.

Developer Overview

Pay In

Pay Out

Pay Ops

Usage

Step 1: Include the Payabli component

Step 2: Define the component container

Step 3: Configure the component

Response examples

Configuration reference

Response object

Developer Overview

Pay In

Pay Out

Pay Ops

​Usage

​Step 1: Include the Payabli component

​Step 2: Define the component container

​Step 3: Configure the component

​Response examples

​Configuration reference

​Response object

Usage

Step 1: Include the Payabli component

Step 2: Define the component container

Step 3: Configure the component

Response examples

Configuration reference

Response object