Sample integration
This page provides a step-by-step integration guide for the fictitious platform PayrollOS to streamline its global payout processes to employees. The integration involves onboarding PayrollOS's customers (depicted by BizCo and MarCo) as connected accounts in Airwallex, PayrollOS pulling funds from the customers’ external bank accounts into their connected account Wallets, and then transferring these funds to the external bank accounts of the employees.
Before you begin
- You must have a pre-configured demo Airwallex platform account with API access. If you don't already have one, contact your Account Manager to get access.
- Obtain your access token API using your unique Client ID and API key. You must have your access token to make API calls.
- You should have demo account credentials (username and password) and a template ID for hosted onboarding to follow this integration guide.
Step 1: Onboard customers onto your platform
Airwallex offers multiple options to onboard connected accounts and submit them for KYC.
- Embedded KYC component (Airwallex-hosted iFrame)
- Hosted flow (Airwallex-hosted full-page redirect)
- Connected Accounts API
As an example, we will be using the Hosted flow (Airwallex-hosted full-page redirect) integration to onboard your customers.
For each of your customers, you will need to:
- Create a connected account.
- Request a URL to redirect your customer to an Airwallex hosted onboarding web form.
- Authorize the URL so your customer can access the onboarding form.
- Verify your customer has successfully onboarded.
Create a connected account
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.
Create a hosted onboarding web form
Once a connected account is created, you will need to onboard your customer through a KYC process to finish activating their account. Airwallex provides multiple options to onboard your customer. The simplest option is to redirect your customer to an online onboarding form that is hosted by Airwallex. 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.
You can start the hosted onboarding process by requesting a hosted flow instance for the connected account. You will need your hosted onboarding template id (template
) and the connected account id (account_id
). You will also need to specify a return_url
to which the customer will be redirected once the onboarding is complete.
A successful request returns an onboarding URL (url
) and a hosted flow instance ID (id
). The onboarding URL must not be shared with the customer until it’s authorized by you to ensure that it’s only intended for this customer.
Verify successful customer onboarding
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.
For a smoother onboarding experience, use account status webhooks to respond to customer account validation in real-time and seamlessly integrate them into your system. By relying on these webhooks, you can eliminate the need for polling and automatically initiate customer onboarding upon validation.
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.
Handle KYC Request for Information (RFI)
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 hosted KYC RFI solution, which has a similar integration setup as hosted onboarding.
Step 2: Fund the customer's Wallet
While you can choose from multiple options to fund the Wallet, BizCo wants to add a US bank account (Linked Account) and pull funds using ACH direct debit. PayrollOS can complete a one-time linkage of BizCo’s external bank account to their connected account with Airwallex. This allows funds to be pulled in over direct debit, avoiding the need for BizCo to ‘push’ funds from their bank account to Airwallex. Please note that applicable limits are in place to mitigate the risk of direct debit recalls.
A Linked Account is a verified external financial account (such as a bank account, credit/debit card, or e-wallet account) that is bound to an Airwallex account. In this sample integration, we will create a Linked Account for BizCo’s US bank account.
Before you can create a Linked Account and add funds via direct debit, you must obtain a direct debit agreement from the external bank account owners. In the demo environment, we can bypass this mandate. For production, see Direct Debit mandate requirements.
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).
Create a Linked Account using Open Banking verification
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 Open Banking to verify the Linked Account.
Get an Open Banking authentication token
Call Generate a Linked Account authentication API to retrieve a Link Token required to access the Open Banking modal.
Create a Linked Account
Call Create a Linked Account API specifying the external bank account location under Linked Account type (e.g. US_BANK) and corresponding bank account information, including information obtained from your Open Banking modal.
Before you can add funds via direct debit from a Linked Account, you must obtain authorization from the external bank account owner in the form of a signed mandate (or signed agreement). You may submit mandate information while creating a Linked Account, or later by calling Update a direct debit mandate API.
You can subscribe to Linked Account webhook events to receive any Linked Account status transitions. See Linked Account statuses for more information.
To create and sign direct debit mandates via API, as a first step, please contact your Airwallex Account Manager to walk you through the direct debit mandate requirements and to enable this capability on your account.
Linked Accounts verified by Open Banking could expire if the external bank account owner changes their login credentials, revokes our access to their account, or naturally after a long period of time (typically above one year).
If the status of your Linked account returns as REQUIRES_ACTION
, call Refresh a Linked Account authentication API to acquire a new Link Token for your Open Banking modal.
Once the Linked Account owner has completed the Open Banking modal, call Complete the Authentication Refresh API to reactivate your Linked Account. You do not need another public token for this request.
A successfully verified Linked Account will return SUCCEEDED
in the status
field. 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.
Fund BizCo’s Wallet via Direct Debit
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 micro-deposit verification.
Step 3: Process payouts
PayrollOS can enable customers to trigger payroll payouts on a one time or recurring basis. In this integration guide, we will demonstrate the flow of a one-time payment where funds will move from each of customers’ connected accounts to the external bank accounts of the employees who are receiving the payout, over Airwallex’s payout rails.
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.
Prepare required beneficiary information
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
Once the beneficiary payload is retrieved, you can 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. You can also use the beneficiary payload to update a beneficiary API that you have already saved with Airwallex.
Create a payout
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.
Retrieve a payout
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.
Fees and pricing
When a payout involves currency conversion (FX), there are two types of fees applied to the connected account:
- FX fees: These cover the cost of converting the payout amount from one currency to another.
- Payout fees: These are separate fees associated with sending the payout itself.
Airwallex allows you to mark up both FX and payout fees. This markup becomes your platform's revenue when your customers make transactions.
Your Account Manager can help you decide how to configure these fees. Options include:
- You can have Airwallex charge the connected accounts directly for FX and payout fees.
- You can cover the FX and payout fees yourself and create a customized pricing model for your product, such as a flat monthly subscription fee via your system.
Reporting and reconciliation
Call Get balance history API and Get list of financial transactions API anytime to retrieve balances and generate financial statements/reports for the purposes of reconciliation, proof of funds, and data analysis. For non-real-time data analysis and reporting requirements, you can also use Platform Reports API to get the data async in a file format and ingest into your data source.
Test and go live
After integrating with Airwallex’s Connected Accounts, Treasury, Payouts products, you can simulate connected account status transition, deposits, payouts, and also test webhooks in the demo environment before going live in the production environment. For more information, see Integration checklist.
Make sure you handle failed payouts before you go live.
Next steps
- Contact your Account Manager if you want to learn more about customizing your hosted flow landing page for business name, logo and color.
- Explore Quotes API if you would like to fix the conversion rate of the payout.