Payment SDK

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(apiAccessId, apiAccessSecret, customerProfileUuid)
deletePaymentMethod(apiAccessId, apiAccessSecret, 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.

`fetchPaymentMethods(apiAccessId, apiAccessSecret, customerProfileUuid): Promise<CustomerContext>`

Fetches saved cards for the specified customer.

Parameters

apiAccessId (string) — Your API access ID.
apiAccessSecret (string) — Your API access secret.
customerProfileUuid (string) — UUID of the customer profile.

Returns

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

`deletePaymentMethod(apiAccessId, apiAccessSecret, customerProfileUuid, paymentMethodUuid): Promise<boolean>`

Deletes a saved payment method.

Parameters

apiAccessId (string)
apiAccessSecret (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
`apiAccessId`	`string`	Your back-end API access ID.
`apiAccessSecret`	`string`	Your back-end API access secret.
`customerProfileUuid`	`string`	UUID of the customer’s profile.
`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 = {
  apiAccessId:       'YOUR_API_ACCESS_ID',
  apiAccessSecret:   'YOUR_API_ACCESS_SECRET',
  customerProfileUuid: 'CUSTOMER_PROFILE_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 = {
        apiAccessId:        'YOUR_API_ID',
        apiAccessSecret:    'YOUR_API_SECRET',
        customerProfileUuid:'CUSTOMER_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>