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

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.

---

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

---

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

---

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>

---