Sample integration

As a platform, you can create Airwallex connected accounts for your customers underneath your platform account. You can then transact on behalf of connected accounts such as debiting funds from the connected account’s Wallet to pay out to external customers.

Initialize the web SDK

Once a connected account is created, you will need to onboard your customers through a KYC process to finish activating their account. The Embedded Component option allows you to use an Airwallex-hosted iFrame to deliver a conversion-optimized, frictionless onboarding experience. The customer submits their documentation, and Airwallex will handle the verification process, any requests for additional information, as well as the approval or rejection of the request.

Before initializing the SDK, you must install the package using either of the following methods.

• Yarn or NPM
  • yarn add @airwallex/components-sdk
  • npm install @airwallex/components-sdk
• CDN
  • <script src="https://static.airwallex.com/components/sdk/v1/index.js"></script>

For more information, see Airwallex Components SDK .

Set up the server for authentication

When the customer, i.e. the connected account holder begins the onboarding process, you will need to get an authorization code to authorize them into the Embedded onboarding workflow. Always get authorization code on the server side, a trusted environment. This prevents malicious users from being able to alter the scope. When the onboarding page loads, on your server, call Authorize a connected account API by providing your Airwallex connected account ID in the x-on-behalf-of header, and the following payload.

The authorization_code is returned in the response, which you should then return to the client side as authCode in order to initialize the Embedded onboarding component.

After your customer finishes onboarding, the status of the connected account will transition to SUBMITTED. Confirm the account status by calling Retrieve a Connected Account API.

As you build your integration, you might want to conduct unit and end-to-end testing of your integration. In the demo environment, you can simulate the KYC process and programmatically transition the account status from SUBMITTED to ACTIVE using the connected account simulation API. Simulation APIs are not available in the production environment.

The sample code below shows how to simulate the status transition for the connected account to ACTIVE.

At this point, your connected account is activated!

See also

• Understanding the difference between Platform Account vs. Connected Account.
• For more information on the hosted flow solution, see Hosted onboarding.
• To explore the other KYC onboarding options, see KYC and onboarding.

In some cases, Airwallex may request additional information from your customers if the information initially provided during KYC is deemed insufficient to approve the application. To handle any requests for information (RFI), we recommend integrating our Embedded KYC RFI solution, which has a similar integration setup as Embedded Components.

As a platform, you can call Linked Accounts API endpoints on behalf of your connected accounts by specifying the connected account's open ID (in the format acct_xxxxxxxx) in the x-on-behalf-of header of your API requests.

Note that currently Airwallex only supports linking bank accounts owned by the business that signed up for the Airwallex account, or by one of its Ultimate Beneficial Owners (UBOs).

To successfully link an external bank account, Airwallex must first verify its ownership. Airwallex offers two options to verify the external bank account: Micro-deposits or Open Banking.

In this sample integration, we'll use the micro-deposits verification to verify that the Linked Account and mandate have been successfully created.

After verification, you will see that the Linked Account status has transitioned to SUCCEEDED. Review status codes to track status transitions when Linked Accounts are created and verified.

Similar to the account status webhook, you can listen to Linked Account webhook events to notify your system that the Linked Account verification is successful.

You can retrieve details of your Linked Account by calling Retrieve a Linked Account API.

After successfully linking BizCo’s Linked Account to its connected account with Airwallex, you can proceed to pull funds from the Linked Account into BizCo’s connected account Wallet using the steps outlined below.

Before you proceed, check funding limits for your platform using Get funding limits API. Platform funding limits determine the maximum amount of direct debit deposits that may be created, and are shared across all Airwallex accounts under your platform account. For more information, see direct debit flight times and funding limits. Contact your Account Manager to increase either the direct debit limit or the Faster Direct Debit limit, and understand our fee schedule for the Faster Direct Debit product.

Call Create a deposit via Direct Debit API to add funds into BizCo’s Wallet by providing BizCo’s Linked Account ID.

Make sure the amount you deposit does not exceed the funding limit.

You can also listen to the deposit.settled webhook to confirm that the deposit is successfully settled into the connected account’s Wallet.

See also

• For detailed instructions on depositing funds into Wallets via direct debits from Linked Accounts, see Add funds via direct debit from Linked Accounts.
• Learn more about Direct Debit funding limits.
• Explore Linked Account using Open Banking verification.

Before creating a payout, you will need to prepare the required beneficiary information, which can vary depending on the payout country/currency, payment method, local clearing system, beneficiary type.

Retrieve the form schema

In this sample integration, we will use Get the form schema API endpoint to programmatically obtain the required beneficiary fields for a given country, currency, payment method, clearing system and entity type. The response also includes validation rules and recommended UI components in JSON format for each field to be rendered on the form.

Validate a beneficiary

Call Validate a beneficiary API to check for errors before creating a beneficiary:

• If validation errors are found, a list of all errors will be returned as a 400 response.
• If all parameters provided for the payout are valid, the endpoint will return a 200 (OK) response.

Create a beneficiary

Proceed to create a beneficiary using the validated beneficiary payload.

In the production environment, you will need to build a generic response handler to parse the validation rules and recommended UI component definitions in the response and adopt them in your application. However, as all schema and field validation rules are maintained by Airwallex, once integrated there will be no further code changes needed on your end when there are updates to the schema.

Call Create a new payout API with the required beneficiary and transaction information (currency, amount, date, reference) to create a payout.

If the source currency is different from the payout currency, an underlying currency conversion will be booked. By default, the prevailing market rate at the point of conversion will be applied to the underlying currency conversion.

Call Retrieve a payout API to get the status of the payout.

The payout status should transition from SCHEDULED to PROCESSING. Listen to the payment.funding.funded webhook to confirm that the payout has been successfully processed.

For detailed information on creating and validating a payout, see create a payout and validate a payout.

See also

• API Schema vs. Form Schema
• Embedded beneficiary component
• Embedded payout component