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 transfer funds from the connected account’s Wallet to their external bank account.

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 Embedded Components solution, see Embedded Components.
• To explore the other KYC onboarding options, see KYC and onboarding.
• Read more about connected account status simulation.

When connected accounts are onboarded as Merchant-Of-Record, you will need to complete the KYB (Know Your Business) onboarding process to start receiving funds via the Airwallex payment acceptance solution. The Embedded KYB component is a pre-built UI element that delivers a conversion-optimized flow, including STP (Straight Through Processing) after submission.

The integration steps for the KYB Embedded component are similar to the KYC component. You will need to initialize the KYB web SDK and add the KYB component to your page. For detailed information, see Embedded KYB Component.

After the connected account is active, Airwallex will begin the KYB review for the requested payment methods.

Call Retrieve Account Capability API to verify the status of the payment method.

The status transitions to ENABLED when the payment method is enabled for the account. This means KYB onboarding has been successful.

You can subscribe to webhook events for a seamless integration. Note that it might take time for the account capability to transition from ENABLED to ACTIVE. To confirm that the payment method capability has been activated and ready for use, check that the status of the payment method is ACTIVE using Retrieve available payment methods types API with query parameter ?active=true.

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.

Call Create a Payment Intent API and specify the connected account ID (connected_account_id field) you want to associate the transaction with.

Provide funds_split_data object directly in the request and specify values for the amount and destination fields. The funds will be automatically split after the Payment Intent has been captured.

Funds will be settled to all customer’s Wallets based on the split portion, where the platform receives the platform fee and the connected account receives the final disbursement amount after deducting the Airwallex fee.

Alternatively, you can split funds using Create a FundsSplit API request. Specify source_id and destination as the payment_intent_id and the connected_account_id respectively. Provide the final disbursement amount to the customer in the amount field after deducting the platform fee and the Airwallex fee.

Please note that a funds split can only be created after the Payment Intent has succeeded and before funds settlement in Airwallex. For most payment methods, the SLA for settlement is 2-3 days after successful payment capture. Subscribe to payment_intent.succeeded webhook to confirm if the payment was successful.

See Funds Split Reversal if you want to reverse an existing funds split made to a connected account, either entirely or partially.

If a funds split has been created incorrectly or the platform would like to retrieve money back from the connected account, a Funds Split Reversal API can be created. The platform can partially reverse a funds split as many times until the entire amount is reversed. A fund split reversal can also happen if there’s a refund request on the original Payment Intent.

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.

Airwallex offers multiple options to collect beneficiary bank account information:

• Native API: Programmatically create payouts with our Payout API endpoints with full control of the beneficiary bank account information collection experience.
• Using API and Form Schema: Programmatically retrieve beneficiary bank account information schema for payout scenarios and render on your user interface.
• Embedded Components: Low-code option to render your beneficiary bank account information collection experience using pre-built UI elements.

Embedded Beneficiary Component

In this sample integration, we will use the Embedded Beneficiary component, which is a pre-built UI element for you to integrate into your own flow for beneficiary (recipient) information collection. It renders the user interface to help you collect required beneficiary information, such as bank account details, business/personal information.

Please note that the Embedded Beneficiary component uses the same API version that you integrate with. As you upgrade API versions, the information rendered in the component will follow suit. This allows you to benefit from the continuous coverage expansion and product enhancements that Airwallex makes over time.

To view and interact with the Embedded Beneficiary component, go to the Embedded Components demo site .

Similar to the Embedded KYC component, you will need to initialize the beneficiary web SDK and add the beneficiary component to your page. For detailed information, see Embedded Beneficiary Component.

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

Once the beneficiary payload is retrieved, you can Create a new beneficiary API in Airwallex. You can also use the beneficiary payload to Update a beneficiary API that you have already saved with Airwallex.

With the beneficiary created, you can use the Embedded payout component to render the user interface to collect required payout information, such as country/region, beneficiary (recipient) type, payment method, amount, date etc., while displaying other important information, such as currency conversion rates and fees. To view and interact with the Embedded Payout component, go to the Embedded Components demo site . Similar to the Embedded Beneficiary component, you will need to initialize the payout web SDK and add the payout component to your page. For detailed information, see Embedded Payout Component.

Note that the payout component does not support Strong Customer Authentication (SCA). You still need to build SCA on top of the component (e.g. two-factor authentications) to comply with regulations such as the second Payment Services Directive (PSD2), if applicable.

After you retrieve the final payout payload from the Embedded Payout component, you can call Create a new payment API . Please make sure that the required beneficiary payload generated using the Embedded beneficiary component has been aggregated into the payout payload. 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