Airwallex currently provides server-side SDK support through its Node.js SDK (Beta).

@airwallex/node-sdk is a TypeScript-first SDK designed for integrating with the Airwallex platform APIs using Node.js. It includes features such as strongly-typed request and response models, built-in error handling, automatic retries, token refresh, and support for custom requests across all Airwallex services — including payment acceptance, issuing, accounts, payouts, and more.

The SDK is currently in Beta and supports API versions from 2025-02-14 onwards. You don’t need to update to the latest SDK versions unless you are adopting a new major API version.

During the Beta phase, we plan to release updates alongside new Client API versions or to deliver patch fixes. We’ll continue refining the SDK during this period to improve stability, and will release a stable version once it’s ready.

Minimum requirements

• Node.js: 14.x
• TypeScript: 4.5x

Installation and setup

Install the package using npm, yarn or pnpm.

Bash
1# npm
2npm install @airwallex/node-sdk@beta
3
4# yarn
5yarn add @airwallex/node-sdk@beta
6
7# pnpm
8pnpm install @airwallex/node-sdk@beta

After completing the installation, you will need to initialize the SDK. The SDK can be configured with the following options:

JavaScript
1import { Airwallex } from '@airwallex/node-sdk';
2
3const client = new Airwallex({
4  // Required fields
5  clientId: 'your_client_id',  // Your Airwallex API client ID
6  apiKey: 'your_api_key',      // Your Airwallex API key
7
8  // Optional fields with defaults
9  env: 'demo',                 // API environment: 'demo','prod'
10  apiVersion: '2025-02-14',    // API version (default: '2025-02-14')
11  timeout: 30000,              // Request timeout in milliseconds (default: 30000)
12  retry: 3,                    // Number of retry attempts for failed requests (default: 3)
13});

Configuration Options

Option	Type	Required	Default	Description
clientId	string	Yes	-	Your Airwallex API client ID.
apiKey	string	Yes	-	Your Airwallex API key.
env	string	No	demo	API environment: demo or production
apiVersion	string	No	2025-02-14	API version
timeout	number	No	30000	Request timeout in milliseconds
enableTelemetry	boolean	No	true	Enable usage analytics
retry	number	No	1	Number of retry attempts for failed requests

API requests

The following sample requests show how to manipulate Airwallex API resources using Node.js SDK.

Example: Creating a card

JavaScript
1// Create a new card
2const newCard = await airwallex.issuing.cards.createCard({
3  authorization_controls: {
4    allowed_merchant_categories: ["7531"],
5    allowed_transaction_count: "SINGLE",
6    transaction_limits: {
7      cash_withdrawal_limits: [
8        {
9          amount: 1000,
10          interval: "PER_TRANSACTION"
11        }
12      ],
13      currency: "USD",
14      limits: [
15        {
16          amount: 1000,
17          interval: "PER_TRANSACTION"
18        }
19      ]
20    }
21  },
22  created_by: "John Smith",
23  form_factor: "VIRTUAL",
24  note: "API SDK Test",
25  request_id: generateRequestId(),
26  cardholder_id: "ef2ba01c-50a2-44e9-ae06-6114d92a9b63",
27  is_personalized: false,
28  program: {
29    purpose: "COMMERCIAL"
30  }
31});
32
33console.log('Card created:', newCard);

Example: Update a card

JavaScript
1// Update a card status
2const updatedCard = await airwallex.issuing.cards.updateCard(cards!.items[0].card_id, {
3   card_status: 'SUSPENDED',
4   reason: 'Temporary suspension for testing',
5 });
6 console.log(`Card updated:`, updatedCard);

Example: Retrieving Cards

JavaScript
1
2// Get active cards
3const cards = await airwallex.issuing.cards.getCards({card_status: 'ACTIVE'});
4console.log('Active cards:', cards);
5
6// Get a specific card by ID
7const cardId = 'card_12345678';
8const cardDetails = await airwallex.issuing.cards.getCardById(cardId);
9console.log('Card details:', cardDetails);

Example: Set custom headers and/or timeout for a request

JavaScript
1const cards = await airwallex.issuing.cards.getCards(
2  {
3    card_status: 'ACTIVE'
4  },
5  {
6    headers: {
7      ‘custom-header1’: ‘value1’
8    },
9    timeout: 50000
10  });

Example: Pagination requests

Right now the SDK doesn’t provide native support for pagination requests. But we can pass the pagination parameters for the requests.

JavaScript
1import { Airwallex, IssuingNonPciCardSummaryDto } from ‘@airwallex/node-sdk’;
2
3// Get all active cards
4const PAGE_SIZE = 10;
5const all_cards: IssuingNonPciCardSummaryDto[] = [];
6let page_num = 0;
7let has_more = false;
8while (has_more) {
9  const cards = await airwallex.issuing.cards.getCards({card_status: 'ACTIVE', page_num: page_num, page_size: PAGE_SIZE});
10  all_cards.push(...cards.items);
11  has_more = cards.has_more;
12  page_num++;
13}
14
15console.log('Active cards:', all_cards);

Example: Processing Payments

JavaScript
1// Create a payment intent
2const paymentIntent = await airwallex.paymentAcceptance.paymentIntents.create({
3  request_id: generateRequestId(),
4  amount: 10.99,
5  currency: 'USD',
6  merchant_order_id: 'order_12345',
7  descriptor: 'Your Company Name',
8  return_url: 'https://your-website.com/return',
9  source: {
10    type: 'card',
11    card: {
12      number: '4012000033330026',
13      expiry_month: '12',
14      expiry_year: '2025',
15      cvc: '123',
16      name: 'John Smith'
17    }
18  }
19});
20
21console.log('Payment intent created:', paymentIntent);
22
23// Confirm the payment intent
24const confirmedPayment = await airwallex.paymentAcceptance.paymentIntents.confirm(
25  paymentIntent.id,
26  {
27    request_id: generateRequestId(),
28    return_url: 'https://your-website.com/return?payment_confirmed=true'
29  }
30);
31
32console.log('Payment confirmed:', confirmedPayment);

Custom API Requests

For API endpoints not explicitly covered by the SDK, you can use the generic request methods:

JavaScript
1// GET request
2const response = await airwallex.get('/api/v1/custom/endpoint', {
3  params: {
4    param1: value1,
5    …
6  },
7  headers: {
8    header1: value1,
9    …
10  }
11});
12
13// POST request
14const createResponse = await airwallex.post('/api/v1/custom/endpoint', {
15  name: 'Test Resource',
16  amount: 1000,
17  currency: 'USD'
18}, {
19  headers: {
20     header1: value1,
21    …
22  }
23});

API responses

The SDK returns a response for every API request. When you create, retrieve, or update an object, the response contains the object itself, including all relevant fields.

Example: Retrieve cards

JSON
1Cards: {
2  has_more: true,
3  items: [
4    {
5      brand: 'VISA',
6      card_id: '84fac3a5-97a3-46ad-97d6-849153ff8252',
7      card_number: '************3717',
8      card_status: 'ACTIVE',
9      cardholder_id: 'c821f1e3-bf71-4f88-b928-e44f1f946995',
10      created_at: '2025-01-02T01:28:33.558+0000',
11      nick_name: 'Adell',
12      updated_at: '2025-01-02T01:28:35.093+0000'
13    },
14    {
15      brand: 'VISA',
16      card_id: 'f0651ef4-dbca-4e3d-8eb7-86990464b6c3',
17      card_number: '************5225',
18      card_status: 'ACTIVE',
19      cardholder_id: 'c821f1e3-bf71-4f88-b928-e44f1f946995',
20      created_at: '2025-01-02T01:28:44.562+0000',
21      nick_name: 'Adrien',
22      updated_at: '2025-01-02T01:28:45.141+0000'
23    },
24    {
25      brand: 'VISA',
26      card_id: '9a36106a-c486-49c1-8e00-c822c3544d34',
27      card_number: '************9114',
28      card_status: 'ACTIVE',
29      cardholder_id: 'c821f1e3-bf71-4f88-b928-e44f1f946995',
30      created_at: '2025-01-02T01:29:47.590+0000',
31      nick_name: 'Savannah',
32      updated_at: '2025-01-02T01:29:47.943+0000'
33    },
34    {
35      brand: 'VISA',
36      card_id: 'eaa0df13-ffed-4aa6-a753-86f82fa2e8da',
37      card_number: '************7745',
38      card_status: 'ACTIVE',
39      cardholder_id: 'c821f1e3-bf71-4f88-b928-e44f1f946995',
40      created_at: '2025-01-02T02:05:38.732+0000',
41      nick_name: 'Mercedes',
42      updated_at: '2025-01-02T02:05:39.068+0000'
43    }
44  ]
45}
46
47Card: {
48  all_card_versions: [
49    {
50      card_number: '************3717',
51      card_status: 'ACTIVE',
52      card_version: 1,
53      created_at: '2025-01-02T01:28:33.558+0000'
54    }
55  ],
56  authorization_controls: {
57    allowed_currencies: [],
58    allowed_merchant_categories: [],
59    allowed_transaction_count: 'MULTIPLE',
60    blocked_transaction_usages: [],
61    transaction_limits: {
62      cash_withdrawal_limits: [Array],
63      currency: 'USD',
64      limits: [Array]
65    }
66  },
67  brand: 'VISA',
68  card_id: '84fac3a5-97a3-46ad-97d6-849153ff8252',
69  card_number: '************3717',
70  card_status: 'ACTIVE',
71  card_version: 1,
72  cardholder_id: 'c821f1e3-bf71-4f88-b928-e44f1f946995',
73  created_at: '2025-01-02T01:28:33.558+0000',
74  created_by: 'card creator from e2e test',
75  delivery_details: {
76    delivery_mode: 'MAIL',
77    delivery_vendor: 'DHL',
78    status: 'PRINTED',
79    tracked: true,
80    tracking_link: 'https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=ABCD1234',
81    tracking_number: 'ABCD1234',
82    updated_at: '2025-04-01T00:00:00.000+0000'
83  },
84  form_factor: 'VIRTUAL',
85  is_personalized: false,
86  name_on_card: 'Tom John',
87  nick_name: 'Adell',
88  note: 'client note for the card',
89  program: { purpose: 'COMMERCIAL', type: 'DEBIT' },
90  purpose: 'BUSINESS_EXPENSES',
91  request_id: 'fd31c758-a12f-4d97-a573-a902b7c7b8a8',
92  updated_at: '2025-01-02T01:28:35.101+0000'
93}

Error handling

The SDK uses specific error types to help you handle different error scenarios:

Error type	Description
ApiError	Base error class for all API-related errors. Properties include: status: HTTP status code data: Error response data from the API headers: Response headers
AuthenticationError	Thrown when authentication fails (extends ApiError).
ValidationError	Thrown when request parameters fail validation (extends ApiError).
RateLimitError	Thrown when API rate limits are exceeded (extends ApiError).
NotFoundError	Thrown when a requested resource doesn't exist (extends ApiError).
AuthorizationError	Thrown when the API client lacks permissions for an operation (extends ApiError).
NetworkError	Thrown for network-related issues like connection failures (extends ApiError).
TimeoutError	Thrown for timeout issues (extends ApiError).
ServerError	Thrown when Airwallex servers return a 5xx error (extends ApiError).

Example

JavaScript
1import { 
2  Airwallex, 
3  ApiError, 
4  AuthenticationError, 
5  ValidationError, 
6} from '@airwallex/node-sdk';
7
8// Example with specific error types
9try {
10  const result = await client.issuing.cards.getCards('ACTIVE');
11  console.log('Operation succeeded:', result);
12} catch (error) {
13  if (error instanceof AuthenticationError) {
14    console.error('Authentication failed. Check your API credentials.');
15    // Refresh credentials or prompt for re-login
16  } 
17  else if (error instanceof ValidationError) {
18    console.error(`Validation error on field '${error.field}': ${error.message}`);
19    // Fix the validation issue
20  }
21  else if (error instanceof ApiError) {
22    console.error(`API Error (${error.status}):`, error.data);
23  }
24  else {
25    console.error('Unexpected error:', error);
26  }
27}

Supported APIs

The SDK provides access to the following Airwallex API modules. Each module contains methods corresponding to the respective Airwallex API endpoints. Refer to the Airwallex API Documentation API for detailed information about specific endpoints and request/response formats.

Account Capability
Account Capability API	/api/v1/account_capabilities/apply /api/v1/account_capabilities/funding_limits /api/v1/account_capabilities/{id} /api/v1/account_capabilities/{id}/enable
Authentication
Authentication API	/api/v1/authentication/login
Authentication Embedded Components API	/api/v1/authentication/authorize
Confirmation Letter
Confirmation Letter API	/api/v1/confirmation_letters/create
Core Resources
Deposits API	/api/v1/deposits /api/v1/deposits/create /api/v1/deposits/{id}
Linked Accounts API	/api/v1/linked_accounts /api/v1/linked_accounts/auth /api/v1/linked_accounts/create /api/v1/linked_accounts/{id} /api/v1/linked_accounts/{id}/auth /api/v1/linked_accounts/{id}/balances /api/v1/linked_accounts/{id}/complete_auth /api/v1/linked_accounts/{id}/confirm /api/v1/linked_accounts/{id}/mandate /api/v1/linked_accounts/{id}/suspend /api/v1/linked_accounts/{id}/verify_microdeposits
Finance
Finance Settlement API	/api/v1/pa/financial/settlements /api/v1/pa/financial/settlements/{id} /api/v1/pa/financial/settlements/{id}/report
Issuing
Issuing Authorizations API	/api/v1/issuing/authorizations /api/v1/issuing/authorizations/{id}
Issuing Cardholders API	/api/v1/issuing/cardholders /api/v1/issuing/cardholders/create /api/v1/issuing/cardholders/{id} /api/v1/issuing/cardholders/{id}/update
Issuing Cards API	/api/v1/issuing/cards /api/v1/issuing/cards/create /api/v1/issuing/cards/{id} /api/v1/issuing/cards/{id}/activate /api/v1/issuing/cards/{id}/details /api/v1/issuing/cards/{id}/limits /api/v1/issuing/cards/{id}/update
Issuing Config API	/api/v1/issuing/config /api/v1/issuing/config/update
Issuing Digital Wallet Tokens API	/api/v1/issuing/digital_wallet_tokens /api/v1/issuing/digital_wallet_tokens/{id}
Issuing Transaction Disputes API	/api/v1/issuing/transaction_disputes /api/v1/issuing/transaction_disputes/create /api/v1/issuing/transaction_disputes/{id} /api/v1/issuing/transaction_disputes/{id}/cancel /api/v1/issuing/transaction_disputes/{id}/submit /api/v1/issuing/transaction_disputes/{id}/update
Issuing Transactions API	/api/v1/issuing/transactions /api/v1/issuing/transactions/{id}
Payment Acceptance
Payment Acceptance Config API	/api/v1/pa/config/applepay/registered_domains /api/v1/pa/config/applepay/registered_domains/add_items /api/v1/pa/config/applepay/registered_domains/remove_items /api/v1/pa/config/banks /api/v1/pa/config/payment_method_types /api/v1/pa/config/reserve_plan
Payment Acceptance Customers API	/api/v1/pa/customers /api/v1/pa/customers/create /api/v1/pa/customers/{id} /api/v1/pa/customers/{id}/generate_client_secret /api/v1/pa/customers/{id}/update
Payment Acceptance Customs Declarations API	/api/v1/pa/customs_declarations/create /api/v1/pa/customs_declarations/{id} /api/v1/pa/customs_declarations/{id}/redeclare /api/v1/pa/customs_declarations/{id}/update
Payment Acceptance Funds Split Destinations API	/api/v1/pa/funds_split_destinations /api/v1/pa/funds_split_destinations/create /api/v1/pa/funds_split_destinations/{id} /api/v1/pa/funds_split_destinations/{id}/disable
Payment Acceptance Funds Split Reversals API	/api/v1/pa/funds_split_reversals /api/v1/pa/funds_split_reversals/create /api/v1/pa/funds_split_reversals/{id}
Payment Acceptance Funds Splits API	/api/v1/pa/funds_splits /api/v1/pa/funds_splits/create /api/v1/pa/funds_splits/{id} /api/v1/pa/funds_splits/{id}/release
Payment Acceptance Payment Attempts API	/api/v1/pa/payment_attempts /api/v1/pa/payment_attempts/{id}
Payment Acceptance Payment Consents API	/api/v1/pa/payment_consents /api/v1/pa/payment_consents/create /api/v1/pa/payment_consents/{id} /api/v1/pa/payment_consents/{id}/disable /api/v1/pa/payment_consents/{id}/update /api/v1/pa/payment_consents/{id}/verify /api/v1/pa/payment_consents/{id}/verify_continue
Payment Acceptance Payment Disputes API	/api/v1/pa/payment_disputes /api/v1/pa/payment_disputes/{id} /api/v1/pa/payment_disputes/{id}/accept /api/v1/pa/payment_disputes/{id}/challenge /api/v1/pa/payment_disputes/{id}/related_payment_intents
Payment Acceptance Payment Intents API	/api/v1/pa/payment_intents /api/v1/pa/payment_intents/create /api/v1/pa/payment_intents/{id} /api/v1/pa/payment_intents/{id}/cancel /api/v1/pa/payment_intents/{id}/capture /api/v1/pa/payment_intents/{id}/confirm /api/v1/pa/payment_intents/{id}/confirm_continue /api/v1/pa/payment_intents/{id}/update
Payment Acceptance Payment Methods API	/api/v1/pa/payment_methods /api/v1/pa/payment_methods/create /api/v1/pa/payment_methods/{id} /api/v1/pa/payment_methods/{id}/disable /api/v1/pa/payment_methods/{id}/update
Payment Acceptance Refunds API	/api/v1/pa/refunds /api/v1/pa/refunds/create /api/v1/pa/refunds/{id}
Payouts
Payouts Beneficiaries API	/api/v1/beneficiaries /api/v1/beneficiaries/create /api/v1/beneficiaries/schema /api/v1/beneficiaries/validate /api/v1/beneficiaries/{id} /api/v1/beneficiaries/{id}/delete /api/v1/beneficiaries/{id}/update /api/v1/beneficiary_api_schemas/generate /api/v1/beneficiary_form_schemas/generate
Payouts Batch Transfers API	/api/v1/batch_transfers /api/v1/batch_transfers/create /api/v1/batch_transfers/{id} /api/v1/batch_transfers/{id}/add_items /api/v1/batch_transfers/{id}/delete /api/v1/batch_transfers/{id}/delete_items /api/v1/batch_transfers/{id}/items /api/v1/batch_transfers/{id}/quote /api/v1/batch_transfers/{id}/submit
Payouts Transfers API	/api/v1/transfers /api/v1/transfers/create /api/v1/transfers/validate /api/v1/transfers/{id} /api/v1/transfers/{id}/cancel /api/v1/transfers/{id}/confirm_funding
Payouts Wallet Transfers API	/api/v1/wallet_transfers /api/v1/wallet_transfers/create /api/v1/wallet_transfers/{wallet_transfer_id}
Risk
Risk Request For Information (RFI) API	/api/v1/rfis /api/v1/rfis/{id} /api/v1/rfis/{id}/respond
Scale
Accounts API	/api/v1/accounts /api/v1/accounts/create /api/v1/accounts/{id} /api/v1/accounts/{id}/submit /api/v1/accounts/{id}/terms_and_conditions/agree /api/v1/accounts/{id}/update /api/v1/account /api/v1/account/amendments/create /api/v1/account/amendments/{amendment_id} /api/v1/account/wallet_info
Scale Invitation Links API	/api/v1/accounts/invitation_links/create /api/v1/accounts/invitation_links/{id}
Scale Settlements Reports API	/api/v1/settlement_reports/prepare /api/v1/settlement_reports/{settlement_report_id}
Simulation
Simulation Sandbox Only Accounts API	/api/v1/simulation/accounts/{account_id}/update_status
Simulation Sandbox Only Cards API	/api/v1/simulation/issuing/create /api/v1/simulation/issuing/{transaction_id}/capture
Simulation Sandbox Only Deposits API	/api/v1/simulation/deposit/create /api/v1/simulation/deposits/{deposit_id}/reject /api/v1/simulation/deposits/{deposit_id}/reverse /api/v1/simulation/deposits/{deposit_id}/settle
Simulation Sandbox Only Payment Acceptance API	/api/v1/simulation/pa/shopper_actions/{action}
Simulation Sandbox Only Payouts API	/api/v1/simulation/payments/{payment_id}/transition
Simulation Sandbox Only Request For Information API	/api/v1/simulation/rfis/create /api/v1/simulation/rfis/{id}/close
Simulation Sandbox Only Transfers API	/api/v1/simulation/transfers/{id}/transition
Transactional FX
Transactional FX Conversion Amendments API	/api/v1/fx/conversion_amendments /api/v1/fx/conversion_amendments/create /api/v1/fx/conversion_amendments/quote /api/v1/fx/conversion_amendments/{conversion_amendment_id} /api/v1/fx/conversions /api/v1/fx/conversions/create /api/v1/fx/conversions/{conversion_id}
Transactional FX Quotes API	/api/v1/fx/quotes/create /api/v1/fx/quotes/{quote_id}
Transactional FX Rates API	/api/v1/fx/rates/current

Versioning: Client API vs. SDK

Client APIs use a date-based versioning system, and new versions are only released when there are backward-incompatible changes. In contrast, SDKs manage implementation details and may receive version updates for various reasons — including backward-compatible changes, backward-incompatible changes, or internal updates like bug fixes, even if the API itself hasn't changed.

SDK semantic versioning format: <Major>.<Minor>.<Patch>-beta.<Beta version>. For example, 1.0.0-beta.1.

• Major^BETA: Follows the existing Platform APIs versioning for backwards-incompatible changes.
• Minor: Follows the existing Platform APIs versioning for backwards-compatible changes.
• Patch^BETA: Reserved for bug fixes and changes that do not introduce changes to the API.
• Beta version: Iteration number of the Beta release.