Skip to main content
The MyGigsters Card SDK lets you embed a fully-featured, single-step card saving form directly into any website. Customers can securely tokenize their payment card through a pre-built, styled UI powered by Airwallex Payment Elements — no backend card-handling required on your side.

Installation

Choose the method that best fits your project — load via a <script> tag for plain HTML sites, or install via npm for React, Vue, Angular, or any bundler-based app. Add the SDK script tag to your HTML page. No build step required.

Full HTML Example

Production CDN URL

Switch the script src to the production URL and set env: "prod" when going live:

Get Client Info (API)

Before initializing the Card SDK, you need your myGigsterId and the customer’s customerId. Call the GET /api/v1/client/me endpoint using your API credentials (HTTP Basic Auth uuid:randomPasswordShowOnce) to retrieve your client profile and myGigsterId. To obtain the customerId, create a customer using the Customer Create API (POST /api/v1/customer). GET /api/v1/client/me

Request Headers

cURL Request Example

Example Response (200 OK)

Response Fields for Card SDK

How It Works

1. Add the SDK to Your Project

Either include the <script> tag for CDN usage (exposes window.MygigstersCard), or install via npm install @mygigsters/card-sdk and import MygigstersCardSDK in your code.

2. Create a Container Element

Add an empty <div> with a unique id (e.g. <div id="mygigsters-card"></div>). The SDK mounts its Airwallex-powered UI inside this element using a closed Shadow DOM for full style isolation.

3. Initialize with Token

Call GET /api/v1/client/me on your backend/app using HTTP Basic Auth (apiKey:apiSecret) to retrieve your token and myGigsterId. Then call .init(config) passing token, myGigsterId, and customerId (from POST /api/v1/customer). The SDK initializes Airwallex and renders the single-step card details modal. API credentials are never passed to the SDK. On success, your onSuccess callback receives a paymentConsentId. Pass this to the MyGigsters backend when creating a charge — no raw card data ever touches your server.

Configuration Options

Pass these options to init():

SDK Methods

After initialization, you can control the card modal programmatically:

Success Response

The onSuccess callback receives a CardSuccessResponse object:

Important Notes

CDN vs npm — Global Name Difference: When using the CDN / script tag, the global object is MygigstersCard. When using the npm package, import the named export MygigstersCardSDK. The API methods are identical for both.
myGigsterId & customerId Requirements: myGigsterId is required to associate the payment consent with the correct account in the MyGigsters system (retrieved via GET /api/v1/client/me). customerId is obtained when creating a customer via POST /api/v1/customer.

Environment URLs

Error Handling

Wrap init() in a try/catch to handle initialization errors:
Runtime errors are surfaced via the onError callback and displayed inline in the modal.

TypeScript

Type definitions are included at dist/index.d.ts:

Direct API Card Capture (Custom UI)

If you prefer to build a custom, bespoke card collection interface rather than using the pre-built Card SDK modal, you can embed Airwallex Elements directly and bind them using MyGigsters card tokenization endpoints:

1. Generate Customer Client Secret

Call POST /api/v1/customer/client-secret to generate an ephemeral Airwallex client secret for the customer.
Key requirement: Request body fields must use camelCase. Note that accountId must be your platform’s myGigsterId (UUID), not the customer’s ID.
Once Airwallex Elements tokenizes the card and returns a payment_consent_id, register it with MyGigsters by calling POST /api/v1/customer/save-consent so future charges and subscriptions can bill this card.

Airwallex Elements Implementation Gotchas

Element Name: expiry (Not cardExpiry)

When mounting split card inputs (e.g., number, expiry, cvc separately), you must name the expiration element expiry. Specifying cardExpiry is unsupported and will fail to mount.

No CSS Variables in Iframe Styles

Airwallex elements are hosted inside secure sandboxed iframes. Because CSS variables (var(--...)) cannot pierce the iframe boundary, styles passed in the configuration object must use raw CSS color literals (such as #111827, rgb(17, 24, 39), or standard font names).

Tab Key Event Trapping

The iframe elements intercept and manage the Tab key internally to cycle focus smoothly across card number, expiry, and CVC. Custom global keydown listeners attached on the host window will not receive keyboard events when focus is inside the card inputs.

Security & Notes

Shadow DOM Isolation

The SDK renders inside a closed Shadow DOM — your page styles never conflict with the card form and host-page scripts cannot reach into the SDK’s DOM.

Pre-fetched Token Authentication

Client applications call GET /api/v1/client/me with Basic Auth (apiKey:apiSecret) to obtain a Bearer JWT token. The token is then passed to the SDK. API keys and secrets are never passed directly to or exposed within the SDK.

PCI-Compliant Card Tokenization

Raw card data is handled exclusively by Airwallex’s PCI-compliant payment elements. Your application only receives the paymentConsentId — never raw card numbers or CVVs.

HTTPS Required

The SDK must be served over HTTPS (or localhost for development). Airwallex payment elements require a secure context. Supported browsers: Chrome 80+, Firefox 78+, Safari 14+, Edge 80+.

Troubleshooting

Container element not found

Make sure the target <div> exists in the DOM before calling init(). In React, call it inside useEffect; in Vue, use mounted().

Token is required error

Ensure you have called GET /api/v1/client/me using your Basic Auth credentials (apiKey:apiSecret) to retrieve the token before initializing the SDK.

Airwallex card element fails to load

Ensure your page is served over HTTPS. Also verify that your Airwallex account has card tokenization enabled, and that the env setting matches your account’s environment.

Card modal appears behind other elements

The modal is mounted on <body> with z-index: 2147483647. If another element has a higher stacking context, adjust accordingly. Need your API key? Head to the Generate API Key section of the MyGigsters Settings to generate one, then start embedding the Card SDK on your website.

Quick reference

Script tag
npm
Last modified on November 10, 2026