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 scriptsrc to the production URL and set env: "prod" when going live:
Get Client Info (API)
Before initializing the Card SDK, you need yourmyGigsterId 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
CallGET /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.
4. Receive the Payment Consent ID
On success, youronSuccess 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 toinit():
SDK Methods
After initialization, you can control the card modal programmatically:Success Response
TheonSuccess 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
Wrapinit() in a try/catch to handle initialization errors:
onError callback and displayed inline in the modal.
TypeScript
Type definitions are included atdist/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
CallPOST /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.2. Save Payment Consent
Once Airwallex Elements tokenizes the card and returns apayment_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 elementexpiry. 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 hostwindow 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 callGET /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 thepaymentConsentId — never raw card numbers or CVVs.
HTTPS Required
The SDK must be served over HTTPS (orlocalhost 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 calledGET /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 theenv 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.
