Payments SDK

A lightweight JavaScript SDK for securely managing customer payment methods using VGS Collect. Loaded via a single CDN script and exposing a simple global API for mounting an "Add Card" form, embedding the GoTab Wallet, and fetching/deleting saved cards.

Installation

Include the SDK bundle in your page:

<script src="https://sdk.gotab.io/payments-sdk.umd.js"></script>

This exposes a global PaymentsSDK object on window.

Global API

window.PaymentsSDK provides these methods:

initAddCardForm(container, config)
initWallet(container, config)
initApplePay(container, config)
fetchPaymentMethods(clientApiAccessId, clientApiAccessSecret, customerProfileUuid)
deletePaymentMethod(clientApiAccessId, clientApiAccessSecret, customerProfileUuid, paymentMethodUuid)

API Reference

`initAddCardForm(container, config)`

Mounts an “Add Card” form into the specified container, handling VGS Collect setup, form fields, styling, and submission.

Parameters

container (HTMLElement | string) — DOM element or CSS selector for rendering the form.
config (PaymentsSDKConfig) — Configuration object (see Configuration).

Behavior

Fetches payment context from your back end (via /api/payment-methods/context/:customerProfileUuid).
Loads the VGS Collect script (vgs-collect.js) from VGS’s CDN.
Renders a React form with fields for first name, last name, email, card number, expiration date, CVC, and ZIP.
Applies any custom styling passed via formProps.
Handles form submission, invoking provided callbacks on success or error.

`initWallet(container, config)`

Mounts the GoTab Wallet interface into the specified container, providing a complete payment management experience for customers.

Parameters

container (HTMLElement | string) — DOM element or CSS selector for rendering the wallet.
config (WalletConfig) — Configuration object (see Wallet Configuration).

Behavior

Creates an embedded iframe containing the GoTab Wallet interface.
Establishes secure communication with the wallet using the provided credentials.
Allows customers to view, add, delete, and manage their saved payment methods.
Supports payment processing with saved cards and digital wallets (Apple Pay, Google Pay).
Handles phone verification and session management automatically.

`initApplePay(container, config)`

Mounts a standalone Apple Pay button into the specified container. Unlike initWallet, this is a payment-only surface — no card management, no phone verification, no saved cards. It loads an embedded iframe that presents the native Apple Pay sheet when the customer taps it.

Parameters

container (HTMLElement | string) — DOM element or CSS selector for rendering the Apple Pay button.
config (ApplePayConfig) — Configuration object (see Apple Pay Configuration).

Behavior

Creates an embedded iframe pointing at the GoTab Apple Pay page for the given tab.
Receives the embedding page's domainName via postMessage so the Apple Pay session can be created against the correct merchant domain.
On tap, opens the native Apple Pay sheet and charges the tab on confirmation.
Emits a PAYMENT_SUCCESS message back to the parent page; the SDK forwards it to your onPaymentSuccess callback.

Requirements

The tab's location must be on the Adyen payment gateway with a digital wallet key configured.
The embedding page must be served over HTTPS in production (Apple Pay requires it).
Apple Pay is only available in Safari/iOS Safari on supported devices — the button will not render on unsupported browsers.

`fetchPaymentMethods(clientApiAccessId, clientApiAccessSecret, customerProfileUuid): Promise<CustomerContext>`

Fetches saved cards for the specified customer.

Parameters

clientApiAccessId (string) — Your client-side API access ID.
clientApiAccessSecret (string) — Your client-side API access secret.
customerProfileUuid (string) — UUID of the customer profile.

Returns

Promise<CustomerContext> resolving to an object { cards: Card[] }.

`deletePaymentMethod(clientApiAccessId, clientApiAccessSecret, customerProfileUuid, paymentMethodUuid): Promise<boolean>`

Deletes a saved payment method.

Parameters

clientApiAccessId (string)
clientApiAccessSecret (string)
customerProfileUuid (string)
paymentMethodUuid (string) — UUID of the payment method to delete.

Returns

Promise<boolean> resolving to true if deletion succeeded.

Configuration

`PaymentsSDKConfig`

Property	Type	Description
`clientApiAccessId`	`string`	Your client-side API access ID.
`clientApiAccessSecret`	`string`	Your client-side API access secret.
`customerProfileUuid`	`string`	UUID of the customer’s profile.
`locationUuid`	`string`	UUID of the location.
`formProps`	`object`	Per-field overrides: placeholder text, styling, icons, etc.
`onLoading?`	`(isLoading: boolean) => void`	Called when the form or submission is loading.
`onSuccess`	`(status: number, data: { card: Card; errors: any }) => void`	Called on successful card add; `data.card` is the new card.
`onError`	`(error: Error) => void`	Called on error (initialization, submission, or validation).
`stateCallback?`	`(state: FieldState) => void`	Optional field-level state updates (focus, validity, error messages).

`WalletConfig`

Property	Type	Description
`clientApiAccessId`	`string`	Your client-side API access ID.
`clientApiAccessSecret`	`string`	Your client-side API access secret.
`tabUuid`	`string`	UUID of the tab associated with this wallet session.
`paymentSessionId`	`string`	Payment session ID for authenticating wallet operations.
`domainName`	`string`	Domain name of the website that contains the iframe.
`onPaymentSuccess`	`(data) => void`	Called on successful payment. See Payment Success Data for details.
`paymentSessionToken?`	`string`	Optional payment session token (if customer is already verified).
`customerId?`	`string`	Optional customer ID (if customer is already verified).
`theme?`	`string`	Optional theme identifier for styling the wallet interface.

`ApplePayConfig`

Property	Type	Description
`tabUuid`	`string`	UUID of the tab to be charged.
`domainName`	`string`	Domain name of the website that contains the iframe.
`onPaymentSuccess`	`(data) => void`	Called on successful payment. See Payment Success Data for details.

Styling the Form

You can customize the appearance of each input by providing CSS-in-JS overrides and custom colors. Define a style object:

const styleOverrides = {
  css: {
    /* your CSS-in-JS rules here */
    boxSizing: 'border-box',
    fontFamily: 'Arial, sans-serif',
    '&::placeholder': { color: '#999999' }
  },
  successColor: '<your-success-color>',
  errorColor: '<your-error-color>'
};

Then add those overrides into the desired field’s props in formProps:

const config = {
  clientApiAccessId:       'YOUR_CLIENT_API_ACCESS_ID',
  clientApiAccessSecret:   'YOUR_CLIENT_API_ACCESS_SECRET',
  customerProfileUuid: 'CUSTOMER_PROFILE_UUID',
  locationUuid: 'LOCATION_UUID',
  formProps: {
    first_name:  { placeholder: 'First name', ...styleOverrides },
    last_name:   { placeholder: 'Last name',  ...styleOverrides },
    email:       { placeholder: 'Email',      ...styleOverrides },
    card_number: { placeholder: 'Card number', showCardIcon: true, ...styleOverrides },
    cvc:         { placeholder: 'CVC',         showCardIcon: true, ...styleOverrides },
    card_exp:    { placeholder: 'MM / YYYY',   ...styleOverrides },
    zip:         { placeholder: 'ZIP code',    ...styleOverrides }
  },

  onLoading:     isLoading => { /* e.g. show spinner */ },
  onSuccess:     (status, data) => { /* handle added card */ },
  onError:       error => { /* handle error */ },
  stateCallback: state => { /* field-level updates */ }
};

All CSS properties and color settings will be applied directly to the corresponding input fields.

Types

`Card`

interface Card {
  payment_method_uuid: string;
  visual_cue:          string;
  payment_type:        string;
  expire_year:         string;
  expire_month:        string;
  name:                string;
  zip:                 string;
}

`FieldState`

interface FieldState {
  isDirty:       boolean;
  isFocused:     boolean;
  isValid:       boolean;
  isEmpty:       boolean;
  isTouched:     boolean;
  errorMessages: string[];
  last4?:        string;
  bin?:          string;
  cardType?:     string;
}

Examples

Add Card Form Example

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Checkout</title>
  </head>
  <body>
    <div id="add-card-root"></div>
    <script src="https://sdk.gotab.io/payments-sdk.umd.js"></script>
    <script>
      // Shared style overrides
      const styleOverrides = {
        css: {
          boxSizing: 'border-box',
          fontFamily: 'Arial, sans-serif',
          '&::placeholder': { color: '#999999' }
        },
        successColor: '#2E8B57',
        errorColor:   '#DC143C'
      };

      // SDK configuration
      const config = {
        clientApiAccessId:        'YOUR_CLIENT_API_ACCESS_ID',
        clientApiAccessSecret:    'YOUR_CLIENT_API_ACCESS_SECRET',
        customerProfileUuid:'CUSTOMER_UUID',
        locationUuid: 'LOCATION_UUID',
        formProps: {
          first_name:  { placeholder: 'First name',  ...styleOverrides },
          last_name:   { placeholder: 'Last name',   ...styleOverrides },
          email:       { placeholder: 'Email address', ...styleOverrides },
          card_number: { placeholder: '•••• •••• •••• ••••', showCardIcon: true, ...styleOverrides },
          cvc:         { placeholder: 'CVC', showCardIcon: true, ...styleOverrides },
          card_exp:    { placeholder: 'MM / YY', ...styleOverrides },
          zip:         { placeholder: 'ZIP code', ...styleOverrides }
        },
        onLoading:     loading => console.log('Loading:', loading),
        onSuccess:     (status, data) => console.log('Added card:', data.card),
        onError:       err => console.error(err),
        stateCallback: state => console.log('Field state:', state)
      };

      // Mount the form
      PaymentsSDK.initAddCardForm('#add-card-root', config);
    </script>
  </body>
</html>

Wallet Example

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>My Wallet</title>
    <style>
      #wallet-container {
        width: 100%;
        max-width: 600px;
        height: 600px;
        margin: 0 auto;
      }
    </style>
  </head>
  <body>
    <div id="wallet-container"></div>
    <script src="https://sdk.gotab.io/payments-sdk.umd.js"></script>
    <script>
      // Wallet configuration
      const walletConfig = {
        clientApiAccessId: 'YOUR_CLIENT_API_ACCESS_ID',
        clientApiAccessSecret: 'YOUR_CLIENT_API_ACCESS_SECRET',
        tabUuid: 'TAB_UUID',
        paymentSessionId: 'PAYMENT_SESSION_ID',
        domainName: 'example.com',
        onPaymentSuccess: (data) => {
          console.log('Payment successful:', data);
          // Handle successful payment (e.g., redirect, show confirmation)
        },
        // Optional: if customer is already verified
        // paymentSessionToken: 'PAYMENT_SESSION_TOKEN',
        // customerId: 'CUSTOMER_ID',
        // Optional: custom theme
        // theme: 'green'
      };

      // Mount the wallet
      PaymentsSDK.initWallet('#wallet-container', walletConfig);
    </script>
  </body>
</html>

Apple Pay Example

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Apple Pay</title>
    <style>
      #apple-pay-container {
        width: 100%;
        max-width: 400px;
        height: 56px;
        margin: 0 auto;
      }
    </style>
  </head>
  <body>
    <div id="apple-pay-container"></div>
    <script src="https://sdk.gotab.io/payments-sdk.umd.js"></script>
    <script>
      const applePayConfig = {
        tabUuid: 'TAB_UUID',
        domainName: window.location.hostname,
        onPaymentSuccess: (data) => {
          console.log('Apple Pay successful:', data);
          // Handle successful payment (e.g., redirect, show confirmation)
        },
      };

      PaymentsSDK.initApplePay('#apple-pay-container', applePayConfig);
    </script>
  </body>
</html>

Payment Success Data

When a payment is successfully processed, the onPaymentSuccess callback receives a data object with the following structure:

{
  payments: Array<{
    amount: number;              // Tab total amount in cents (e.g., 690 = $6.90)
    customer_fee: number;        // Customer fee in cents (e.g., 32 = $0.32)
    gateway: string;             // Payment gateway used (e.g., "ADYEN")
    payment_id: string;          // Unique payment identifier
    payment_type: string;        // Card type (e.g., "VISA", "MASTERCARD")
    processor_id: string;        // Processor identifier
  }>;
  tab_uuid: string;              // UUID of the tab
  amount: number;                // Tab total in cents
}

Example:

onPaymentSuccess: (data) => {
  console.log('Payment successful:', data);

  // Access payment details
  const payment = data.payments[0];
  const amountDollars = payment.amount / 100;
  const customerFeeDollars = payment.customer_fee / 100;
  const totalDollars = (payment.amount + payment.customer_fee) / 100;

  console.log(`Charged: $${totalDollars.toFixed(2)}`);
  console.log(`Payment ID: ${payment.payment_id}`);
  console.log(`Card Type: ${payment.payment_type}`);
}