Payment 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, mounting an Apple Pay button, 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:

Method	Description
initAddCardForm(container, config)	Mounts an “Add Card” form for saving payment methods.
initApplePay(container, config)	Mounts a standalone Apple Pay button.
fetchPaymentMethods(clientApiAccessId, clientApiAccessSecret, customerProfileUuid)	Fetches saved cards for a customer.
deletePaymentMethod(clientApiAccessId, clientApiAccessSecret, customerProfileUuid, paymentMethodUuid)	Deletes a saved payment method.

---

API Reference

initAddCardForm(container, config)

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

Parameters

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

Behavior

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

---

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

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

Behavior

1. Creates an embedded iframe pointing at the GoTab Apple Pay page for the given tab.
2. Receives the embedding page’s domainName via postMessage so the Apple Pay session can be created against the correct merchant domain.
3. On tap, opens the native Apple Pay sheet and charges the tab on confirmation.
4. 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)

Fetches saved cards for the specified customer.

Parameters

Parameter	Type	Description
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)

Deletes a saved payment method.

Parameters

Parameter	Type	Description
clientApiAccessId	string	Your client-side API access ID.
clientApiAccessSecret	string	Your client-side API access secret.
customerProfileUuid	string	UUID of the customer profile.
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).

---

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

<!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>
      const styleOverrides = {
        css: {
          boxSizing: 'border-box',
          fontFamily: 'Arial, sans-serif',
          '&::placeholder': { color: '#999999' }
        },
        successColor: '#2E8B57',
        errorColor:   '#DC143C'
      };

      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)
      };

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

---

Apple Pay

<!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) => {
  const payment          = data.payments[0];
  const amountDollars    = payment.amount / 100;
  const feeDollars       = 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}`);
}