GoTab Wallet

Embed GoTab Wallet so customers can check out or manage their saved cards.

Use GoTab Wallet when GoTab should authenticate the customer, display cards from their Wallet account, and submit the payment inside your checkout. You can also mount Wallet without a tab to let a customer manage those cards. In checkout mode, your server creates the tab and payment session, Wallet submits the payment, and your server confirms the result.

Cards saved in Wallet belong to the customer’s Wallet account. To select a card saved under an integration customer profile and submit the payment through the Integrations API, use the stored-card payment flow instead.

Choose a Wallet mode

initWallet selects its mode from tabUuid and paymentSessionId:

Mode	`tabUuid`	`paymentSessionId`	Behavior
Checkout	Required	Required	Wallet authenticates the customer, selects or adds a payment method, and pays the tab.
Card management	Omit	Omit	Wallet manages the GoTab Wallet customer’s cards without loading or paying a tab.

Supplying only one of tabUuid or paymentSessionId throws an error. Do not also submit the payment through the Integrations API.

Prepare to embed Wallet

Before mounting either mode:

Obtain the separately issued browser SDK credentials from GoTab API Support. Do not use your Integrations API access secret.
Ask GoTab API Support to add every production origin that will embed Wallet, call collectPaymentCustomerContext, or mount Payment Action to the integration’s gotab_wallet_allowed_origins setting. Provide each exact HTTPS origin, including any non-default port. Despite the setting’s name, the same origin list authorizes all three capabilities, even when the integration does not otherwise use Wallet.
If your page enforces a Content Security Policy, add the GoTab origin provided for your environment to frame-src.
Give the Wallet container a stable height that can accommodate sign-in, card forms, and payment challenges.

Wallet fills the dimensions of its container. Set the container height explicitly and test it at the viewport sizes your checkout supports.

Both modes load through the Payment SDK:

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

This exposes window.PaymentsSDK.

Set up Wallet checkout

Checkout setup crosses your server and browser. Create the tab and payment session on your server before you mount Wallet in the browser.

Create the payment session

Create the tab with a supported guest identifier, such as phoneNumber, but without an integration customerId. Then call POST /api/v2/loc/{location}/payment-sessions/{tabUuid} with your server-side Integrations API bearer token:

const response = await fetch(
  `${gotabApiOrigin}/api/v2/loc/${locationUuid}/payment-sessions/${tabUuid}`,
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${gotabBearerToken}` },
  },
);

if (!response.ok) throw new Error('Unable to start the Wallet session');

const {
  data: { paymentSessionId, expires },
} = await response.json();

Send paymentSessionId—not the bearer token—to the browser. The expires value tells your server how long the payment session is available.

Mount Wallet and verify the result

Replace TAB_UUID and PAYMENT_SESSION_ID with the values produced by your server, and replace the client credential placeholders with the separately issued browser SDK credentials. This example gives Wallet a stable container and blocks fulfillment until the server confirms the tab:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Checkout</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>
      const tabUuid = 'TAB_UUID';

      const walletConfig = {
        clientApiAccessId:     'YOUR_CLIENT_API_ACCESS_ID',
        clientApiAccessSecret: 'YOUR_CLIENT_API_ACCESS_SECRET',
        tabUuid,
        paymentSessionId:      'PAYMENT_SESSION_ID',
        theme:                 'gotab',
        onPaymentSuccess: async (data) => {
          console.log('Wallet payment completed:', data);

          // Application-owned: retrieve the latest tab through your server.
          const tab = await confirmTabOnYourServer(tabUuid);
          if (tab.status === 'CLOSED' && tab.balanceDue === 0) {
            fulfillOrder();
          } else {
            showPaymentStillProcessing();
          }
        },
      };

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

The Wallet sign-in interface should render inside #wallet-container. In this example:

confirmTabOnYourServer asks your server to retrieve the latest tab from GoTab.
fulfillOrder completes your application’s order flow only after the tab is closed with no balance due.
showPaymentStillProcessing keeps the customer informed while preventing another payment attempt.

The callback reports that Wallet observed a completed payment. The server-confirmed closed tab with no balance due is the proof that your application can fulfill the order.

Recover an interrupted checkout

This section applies to Wallet checkout mode. GoTab can enable 3D Secure 2 (3DS2) for eligible card payments at a location. Enabling 3DS2 does not mean every customer will see a challenge: a payment may complete without interaction, or the card issuer may ask the customer to verify it.

Wallet displays the verification steps when they are required. In some cases, the customer is redirected for verification and then returned to your checkout.

After the customer returns, mount initWallet again with the same tabUuid and paymentSessionId. The SDK resumes the existing payment automatically.

Refreshing or leaving the page during verification does not necessarily cancel the payment. Until your server confirms its result:

Do not submit another payment for the tab.
Remount Wallet with the same checkout identifiers when the customer returns.
Fetch the latest tab from your server before enabling another payment method or completing the order.

Event	What your integration does next
Wallet calls `onPaymentSuccess`	Update the checkout UI, then confirm the final tab state through your server.
The customer returns from verification	Remount Wallet with the same `tabUuid` and `paymentSessionId`; Wallet resumes the existing payment.
The page refreshes or no callback arrives	Retrieve the latest tab through your server before changing the checkout. Remount Wallet with the same identifiers if payment is not yet final.
Wallet cannot resume the session	Keep payment controls disabled until your server confirms whether the existing payment completed, remains active, or can be retried.

Payment success data

onPaymentSuccess receives a tab and payment summary:

interface WalletPaymentSuccess {
  payments: Array<{
    payment_id:    string;  // GoTab payment identifier
    amount?:       number;  // Payment amount in minor currency units
    customer_fee?: number;  // Customer fee in minor currency units
    gateway?:      string;  // Payment gateway
    payment_type?: string;  // Card brand or payment type
    processor_id?: string;  // Processor transaction identifier
  }>;
  tab_uuid: string;  // Paid tab UUID
  amount:   number;  // Total charge, including customer fee
}

Amounts use the location’s minor currency unit, such as cents for USD. Some payment details are optional. After 3DS2 verification, payments may contain only payment_id; use the top-level amount for display and fetch the latest tab on your server for complete payment details.

Use the callback payload to update the checkout UI. Complete the order only after your server retrieves the tab and confirms its final state and balance, as shown in the checkout example.

Mount card-management mode

After completing the shared embed preparation, omit both checkout identifiers when you mount Wallet:

PaymentsSDK.initWallet('#wallet-container', {
  clientApiAccessId,
  clientApiAccessSecret,
  theme: 'gotab',
});

After the customer authenticates, Wallet displays their Wallet cards without loading or paying a tab. It does not manage cards stored under an integration customer_profile_uuid.

Configuration

`initWallet(container, config)`

container accepts an HTMLElement or a CSS selector. The configuration determines whether Wallet opens in checkout or card-management mode.

Property	Type	Required	Description
`clientApiAccessId`	`string`	Yes	Public browser SDK access ID.
`clientApiAccessSecret`	`string`	Yes	Browser SDK access credential. Do not use your Integrations API access secret.
`tabUuid`	`string`	Checkout only	UUID of the tab created without an integration `customerId`. Must be supplied with `paymentSessionId`.
`paymentSessionId`	`string`	Checkout only	Server-created payment session for `tabUuid`. Must be supplied with `tabUuid`.
`theme`	`WalletTheme`	No	Wallet theme; defaults to `gotab`.
`onPaymentSuccess`	`(data) => void`	No	Runs after Wallet completes the payment. Use it for checkout unless your server has another reconciliation path.

Wallet derives the embedding domain from window.location.hostname; domainName is not a WalletConfig property.

WalletTheme accepts gotab (the default), brand, brick, gray, green, magenta, orange, persimmon, purple, red, sunshine, summer, warm-blue, warm-red, or aqua-tangerine.

Preverified Wallet sessions

Most integrations should omit these properties. Include them only when GoTab provides both values for a preverified Wallet session:

Property	Type	Description
`paymentSessionToken`	`string`	Token supplied by GoTab for the preverified session.
`customerId`	`string`	Wallet customer paired with that token. This is not the integration `customer_id`.

Prepare Wallet for production

Content Security Policy

If your page enforces a Content Security Policy, add the GoTab origin provided for your environment to frame-src. If the same page uses other SDK capabilities, merge their sources from the Payment SDK CSP table.

Release checks

Register every embedding origin with GoTab.
Keep a stable container height at narrow and wide viewports.
Do not add payment-session tokens to your own URLs or logs.
In the environment provided by GoTab, test successful and refused payments, interrupted verification, refresh and return, a lost callback, and repeated clicks while payment is pending.
Validate the production-origin allowlist separately from payment-outcome testing.
Test keyboard navigation and every supported container size from the production origin.