# Server-side SDKs 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. ```shell # npm npm install @airwallex/node-sdk@beta # yarn yarn add @airwallex/node-sdk@beta # pnpm pnpm 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 import { Airwallex } from '@airwallex/node-sdk'; const client = new Airwallex({ // Required fields clientId: 'your_client_id', // Your Airwallex API client ID apiKey: 'your_api_key', // Your Airwallex API key // Optional fields with defaults env: 'demo', // API environment: 'demo','prod' apiVersion: '2025-02-14', // API version (default: '2025-02-14') timeout: 30000, // Request timeout in milliseconds (default: 30000) retry: 3, // Number of retry attempts for failed requests (default: 3) }); ``` ### 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 // Create a new card const newCard = await airwallex.issuing.cards.createCard({ authorization_controls: { allowed_merchant_categories: ["7531"], allowed_transaction_count: "SINGLE", transaction_limits: { cash_withdrawal_limits: [ { amount: 1000, interval: "PER_TRANSACTION" } ], currency: "USD", limits: [ { amount: 1000, interval: "PER_TRANSACTION" } ] } }, created_by: "John Smith", form_factor: "VIRTUAL", note: "API SDK Test", request_id: generateRequestId(), cardholder_id: "ef2ba01c-50a2-44e9-ae06-6114d92a9b63", is_personalized: false, program: { purpose: "COMMERCIAL" } }); console.log('Card created:', newCard); ``` #### Example: Update a card ```javascript // Update a card status const updatedCard = await airwallex.issuing.cards.updateCard(cards!.items[0].card_id, { card_status: 'SUSPENDED', reason: 'Temporary suspension for testing', }); console.log(`Card updated:`, updatedCard); ``` #### Example: Retrieving Cards ```javascript // Get active cards const cards = await airwallex.issuing.cards.getCards({card_status: 'ACTIVE'}); console.log('Active cards:', cards); // Get a specific card by ID const cardId = 'card_12345678'; const cardDetails = await airwallex.issuing.cards.getCardById(cardId); console.log('Card details:', cardDetails); ``` #### Example: Set custom headers and/or timeout for a request ```javascript const cards = await airwallex.issuing.cards.getCards( { card_status: 'ACTIVE' }, { headers: { ‘custom-header1': ‘value1' }, timeout: 50000 }); ``` #### 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 import { Airwallex, IssuingNonPciCardSummaryDto } from ‘@airwallex/node-sdk'; // Get all active cards const PAGE_SIZE = 10; const all_cards: IssuingNonPciCardSummaryDto[] = []; let page_num = 0; let has_more = false; while (has_more) { const cards = await airwallex.issuing.cards.getCards({card_status: 'ACTIVE', page_num: page_num, page_size: PAGE_SIZE}); all_cards.push(...cards.items); has_more = cards.has_more; page_num++; } console.log('Active cards:', all_cards); ``` #### Example: Processing Payments ```javascript // Create a payment intent const paymentIntent = await airwallex.paymentAcceptance.paymentIntents.create({ request_id: generateRequestId(), amount: 10.99, currency: 'USD', merchant_order_id: 'order_12345', descriptor: 'Your Company Name', return_url: 'https://your-website.com/return', source: { type: 'card', card: { number: '4012000033330026', expiry_month: '12', expiry_year: '2025', cvc: '123', name: 'John Smith' } } }); console.log('Payment intent created:', paymentIntent); // Confirm the payment intent const confirmedPayment = await airwallex.paymentAcceptance.paymentIntents.confirm( paymentIntent.id, { request_id: generateRequestId(), return_url: 'https://your-website.com/return?payment_confirmed=true' } ); console.log('Payment confirmed:', confirmedPayment); ``` ### Custom API Requests For API endpoints not explicitly covered by the SDK, you can use the generic request methods: ```javascript // GET request const response = await airwallex.get('/api/v1/custom/endpoint', { params: { param1: value1, … }, headers: { header1: value1, … } }); // POST request const createResponse = await airwallex.post('/api/v1/custom/endpoint', { name: 'Test Resource', amount: 1000, currency: 'USD' }, { headers: { header1: value1, … } }); ``` ## 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 Cards: { has_more: true, items: [ { brand: 'VISA', card_id: '84fac3a5-97a3-46ad-97d6-849153ff8252', card_number: '************3717', card_status: 'ACTIVE', cardholder_id: 'c821f1e3-bf71-4f88-b928-e44f1f946995', created_at: '2025-01-02T01:28:33.558+0000', nick_name: 'Adell', updated_at: '2025-01-02T01:28:35.093+0000' }, { brand: 'VISA', card_id: 'f0651ef4-dbca-4e3d-8eb7-86990464b6c3', card_number: '************5225', card_status: 'ACTIVE', cardholder_id: 'c821f1e3-bf71-4f88-b928-e44f1f946995', created_at: '2025-01-02T01:28:44.562+0000', nick_name: 'Adrien', updated_at: '2025-01-02T01:28:45.141+0000' }, { brand: 'VISA', card_id: '9a36106a-c486-49c1-8e00-c822c3544d34', card_number: '************9114', card_status: 'ACTIVE', cardholder_id: 'c821f1e3-bf71-4f88-b928-e44f1f946995', created_at: '2025-01-02T01:29:47.590+0000', nick_name: 'Savannah', updated_at: '2025-01-02T01:29:47.943+0000' }, { brand: 'VISA', card_id: 'eaa0df13-ffed-4aa6-a753-86f82fa2e8da', card_number: '************7745', card_status: 'ACTIVE', cardholder_id: 'c821f1e3-bf71-4f88-b928-e44f1f946995', created_at: '2025-01-02T02:05:38.732+0000', nick_name: 'Mercedes', updated_at: '2025-01-02T02:05:39.068+0000' } ] } Card: { all_card_versions: [ { card_number: '************3717', card_status: 'ACTIVE', card_version: 1, created_at: '2025-01-02T01:28:33.558+0000' } ], authorization_controls: { allowed_currencies: [], allowed_merchant_categories: [], allowed_transaction_count: 'MULTIPLE', blocked_transaction_usages: [], transaction_limits: { cash_withdrawal_limits: [Array], currency: 'USD', limits: [Array] } }, brand: 'VISA', card_id: '84fac3a5-97a3-46ad-97d6-849153ff8252', card_number: '************3717', card_status: 'ACTIVE', card_version: 1, cardholder_id: 'c821f1e3-bf71-4f88-b928-e44f1f946995', created_at: '2025-01-02T01:28:33.558+0000', created_by: 'card creator from e2e test', delivery_details: { delivery_mode: 'MAIL', delivery_vendor: 'DHL', status: 'PRINTED', tracked: true, tracking_link: 'https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=ABCD1234', tracking_number: 'ABCD1234', updated_at: '2025-04-01T00:00:00.000+0000' }, form_factor: 'VIRTUAL', is_personalized: false, name_on_card: 'Tom John', nick_name: 'Adell', note: 'client note for the card', program: { purpose: 'COMMERCIAL', type: 'DEBIT' }, purpose: 'BUSINESS_EXPENSES', request_id: 'fd31c758-a12f-4d97-a573-a902b7c7b8a8', updated_at: '2025-01-02T01:28:35.101+0000' } ``` ## 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: | | 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). | > **\[WARNING]** > > **Retryable errors**: Only ServerError, TimeoutError, NetworkError will be retried by the SDK if retry is enabled. ### Example ```javascript import { Airwallex, ApiError, AuthenticationError, ValidationError, } from '@airwallex/node-sdk'; // Example with specific error types try { const result = await client.issuing.cards.getCards('ACTIVE'); console.log('Operation succeeded:', result); } catch (error) { if (error instanceof AuthenticationError) { console.error('Authentication failed. Check your API credentials.'); // Refresh credentials or prompt for re-login } else if (error instanceof ValidationError) { console.error(`Validation error on field '${error.field}': ${error.message}`); // Fix the validation issue } else if (error instanceof ApiError) { console.error(`API Error (${error.status}):`, error.data); } else { console.error('Unexpected error:', error); } } ``` ## 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 API | /api/v1/account\_capabilities/apply /api/v1/account\_capabilities/funding\_limits /api/v1/account\_capabilities/{id} /api/v1/account\_capabilities/{id}/enable | | | | | Authentication API | /api/v1/authentication/login | | Authentication Embedded Components API | /api/v1/authentication/authorize | | | | | Confirmation Letter API | /api/v1/confirmation\_letters/create | | | | | 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 Settlement API | /api/v1/pa/financial/settlements /api/v1/pa/financial/settlements/{id} /api/v1/pa/financial/settlements/{id}/report | | | | | 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 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 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 Request For Information (RFI) API | /api/v1/rfis /api/v1/rfis/{id} /api/v1/rfis/{id}/respond | | | | | 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 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 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: `..-beta.`. 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.