Server-side SDKs (Beta)

Learn how to install and use Airwallex's server-side SDKs

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.

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

JavaScript

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

Example: Update a card

JavaScript

Example: Retrieving Cards

JavaScript

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

JavaScript

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

Example: Processing Payments

JavaScript

Custom API Requests

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

JavaScript

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

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).

Retryable errors: Only ServerError, TimeoutError, NetworkError will be retried by the SDK if retry is enabled.

Example

JavaScript

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 Demo Only Accounts API	/api/v1/simulation/accounts/{account_id}/update_status
Simulation Demo Only Cards API	/api/v1/simulation/issuing/create /api/v1/simulation/issuing/{transaction_id}/capture
Simulation Demo 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 Demo Only Payment Acceptance API	/api/v1/simulation/pa/shopper_actions/{action}
Simulation Demo Only Payouts API	/api/v1/simulation/payments/{payment_id}/transition
Simulation Demo Only Request For Information API	/api/v1/simulation/rfis/create /api/v1/simulation/rfis/{id}/close
Simulation Demo 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.

Server-side SDKs (Beta)

.css-1xcsryl>.e1x8zjqq1{opacity:0;-webkit-transition:opacity 250ms ease-in-out;transition:opacity 250ms ease-in-out;}.css-1xcsryl:hover>.e1x8zjqq1{opacity:1;}Minimum requirements.css-158icaa{margin-left:4px;}

Installation and setup

Configuration Options

API requests

Example: Creating a card

Example: Update a card

Example: Retrieving Cards

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

Example: Pagination requests

Example: Processing Payments

Custom API Requests

API responses

Example: Retrieve cards

Error handling

Example

Supported APIs

Versioning: Client API vs. SDK

Minimum requirements