How to use

1. install npm package using npm, pnpm or yarn

npm install @airwallex/node-sdk@beta
// or
pnpm install @airwallex/node-sdk@beta
// or
yarn add @airwallex/node-sdk@beta

2. initialize Airwallex instance

import { Airwallex } from '@airwallex/awx-node-sdk';
  const airwallex = new Airwallex({
    clientId: 'YOUR CLIENT ID',
    apiKey: 'YOUR API KEY',
    env: 'demo', // can be 'demo' or 'prod'
  });

3. call the endpoint

  // for example, if you want to get cards and handle the error
    const cards = await airwallex.issuing.cards.getCards({ card_status: 'ACTIVE' }).catch(error => {
      if (error instanceof ApiError) {
        console.log('Error: ', error);
      } else {
        throw new Error('Unknown error: ' + error);
      }
    });

  // for example, if you want to create a card
  const card = 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"
      }
    }
  );

  # for example, if you want to use a custom header and timeout
  const card = 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"
            }
          ]
        }
      },
      ...
    },
    {
      headers: {
          'x-on-behalf-of': 'account_id'
      },
      timeout: 10000
    },
  );

  // for example, if you want to call a undocumented/experimental endpoint
  const cards = await airwallex.get('/api/v1/issuing/cards', {
      params: {
          card_status: 'ACTIVE'
      },
      headers: {
          'x-on-behalf-of': 'account_id'
      },
      timeout: 10000
  }).catch(error => {
      if (error instanceof ApiError) {
          console.log('Error: ', error);
      } else {
          throw new Error('Unknown error: ' + error);
      }
  });

Versioning

SDK versions follows semantic versioning.

Major version: Follows the existing Platform APIs Versioning for backwards incompatible changes.

Minor version: Follows the existing Platform APIs Versioning for backwards compatible changes.

Patch version: Reserved for bug fixes and changes that do not introduce changes to the API.

The SDK is in Beta. The version format is '..-beta.' like 1.0.0-beta.1.

Airwallex Client APIs are currently version controlled using a date-based format, only creating new versions whenever backward incompatible changes are released.

For SDK 1.0.0-beta.1, it supports API version 2025-02-14 and has limited support for later API versions.

During Beta, we expect to release a new version of the SDK alongside new Client API versions or patch fixes.

Available options for creating airwallex instance

| Option | Required | Type | Description |Default | |-----------------|----------|---------|------------------------------------|--------- | clientId | Yes | string | Can be obtained from webapp | / | | apiKey | Yes | string | Can be obtained from webapp | / | | env | Yes | string | 'demo' / 'prod' | demo | | timeout | No | number | Timeout for HTTP requests (ms) | 30000 | | enableTelemetry | No | boolean | Enable telemetry for HTTP requests | true | | retry | No | number | Number of retries for HTTP requests| 1 | | retryDelay | No | number | Base delay between retries (ms) | 300 |

Error Handling

The SDK provides several error types to help you handle different kinds of errors that might occur during API calls.

Error Types

| Error Type | HTTP Status | Description | When It Occurs | |------------|-------------|-------------|---------------| | ApiError | Any | Base error class for all API-related errors | Parent class for all specific error types | | NetworkError | N/A | Network connectivity issues | When the client can't connect to the server (e.g., network down, DNS failure) | | TimeoutError | N/A | Request timeout | When the request takes too long to complete | | AuthenticationError | 401 | Authentication failed | Invalid or expired credentials | | AuthorizationError | 403 | Authorization failed | Valid credentials but insufficient permissions | | NotFoundError | 404 | Resource not found | When the requested resource doesn't exist | | ValidationError | 400 | Request validation failed | Invalid request parameters or payload | | RateLimitError | 429 | Rate limit exceeded | Too many requests in a short time period | | ServerError | 500+ | Server-side error | Internal server error or service unavailable |

Error Properties

All error instances include the following properties:

• message: Human-readable error message
• name: The name of the error type (e.g., "ValidationError")
• status: HTTP status code (when applicable)
• data: Additional error details from the API response
• headers: Response headers

Retryable Errors

The SDK automatically retries requests for errors that are considered retryable:

• TimeoutError
• NetworkError

You can configure retry behavior when initializing the client.

example use cases

There's some example scripts under ./examples.

The steps to run these scripts:

1. Set up the env variables for the corresponding client ID and API key in .env. Consult the account manager if there're permission issues.

2. Install ts-node or npx.

3. Run the script like ts-node ./examples/pa.ts or npx node ./examples/pa.ts.

For ./examples/pa.ts, it runs the use case for Guest User Checkout.

The operations in the script:

1. Get the customer list
2. Create a new customer
3. Get the payment intent list
4. Create a payment intent for the new customer
5. Confirm the payment intent

The output looks like:

Customers: {
  has_more: false,
  items: [
    {
      id: 'custom_id',
      request_id: '992d802a-d0c9-42ae-ae74-20959bcb0b0b',
      merchant_customer_id: 'merchant_customer_id',
      email: '[email protected]',
      phone_number: '',
      created_at: '2025-03-26T22:16:40+0000',
      updated_at: '2025-03-26T22:16:40+0000'
    },
    ...
  ]
}
Customer created: {
  id: 'new_customer_id',
  request_id: 'c3a8463a-5a0d-46bf-97d3-bc676e1a972d',
  merchant_customer_id: 'a_merchant_customer_id',
  email: '[email protected]',
  phone_number: '',
  client_secret: 'xxxxxxxx',
  created_at: '2025-03-26T22:19:00+0000',
  updated_at: '2025-03-26T22:19:00+0000'
}
Payment Intents: {
  has_more: true,
  items: [
    {
      latest_payment_attempt: [Object],
      id: 'int_hkdmfsn96h5unqewweg',
      request_id: '341d2a4b-58fb-40c2-9533-457fb3c387ad',
      amount: 100,
      currency: 'USD',
      merchant_order_id: '5e7925f4-42e3-44b1-9a20-79254aef48dd',
      descriptor: 'Pa Test',
      status: 'SUCCEEDED',
      captured_amount: 100,
      created_at: '2025-03-26T22:16:41+0000',
      updated_at: '2025-03-26T22:16:42+0000'
    },
    ...
  ]
}
Payment Intent created: {
  id: 'payment_intent_id',
  request_id: '8109f8b2-1bbe-4f22-ae94-874c3daf156c',
  amount: 100,
  currency: 'USD',
  merchant_order_id: 'merchant_order_id',
  descriptor: 'Pa Test',
  status: 'REQUIRES_PAYMENT_METHOD',
  captured_amount: 0,
  created_at: '2025-03-26T22:19:00+0000',
  updated_at: '2025-03-26T22:19:00+0000',
  client_secret: 'xxxxxxx',
  original_amount: 100,
  original_currency: 'USD'
}
Payment Intent confirmed: {
  latest_payment_attempt: {
    id: 'attempt_id',
    amount: 100,
    currency: 'USD',
    payment_method: { type: 'card', card: [Object] },
    merchant_order_id: 'merchant_order_id',
    payment_intent_id: 'payment_intent_id',
    status: 'AUTHORIZED',
    provider_transaction_id: 'provider_transaction_id',
    payment_method_transaction_id: 'payment_method_transaction_id',
    provider_original_response_code: '00',
    authorization_code: 'xxxxxx',
    captured_amount: 0,
    refunded_amount: 0,
    created_at: '2025-03-26T22:19:01+0000',
    updated_at: '2025-03-26T22:19:02+0000',
    settle_via: 'airwallex',
    authentication_data: {
      ds_data: [Object],
      fraud_data: [Object],
      avs_result: 'not_attempted',
      cvc_result: 'matched',
      cvc_code: 'M'
    },
    payment_method_options: { card: [Object] }
  },
  id: 'payment_intent_id',
  request_id: '7f278406-285d-48a3-bb10-8a28766f2fc3',
  amount: 100,
  currency: 'USD',
  merchant_order_id: 'merchant_order_id',
  descriptor: 'Pa Test',
  status: 'SUCCEEDED',
  captured_amount: 100,
  created_at: '2025-03-26T22:19:00+0000',
  updated_at: '2025-03-26T22:19:02+0000',
  original_amount: 100,
  original_currency: 'USD'
}