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 '<Major>.<Minor>.<Patch>-beta.<beta version number>' 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

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 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: 'john@example.com',
      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: 'john@example.com',
  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'
}