Integration guide

A typical use case involves paying vendor bills on ERPs or accounts payable management software through a connected Airwallex account. Customers will upload bills to your platform, undergo an approval process, and seamlessly execute payouts to vendors through integration with Airwallex. This eliminates the need to manually enter vendor payment details and initiate transfers via the Airwallex Webapp.

To build such an integration, you will need the following OAuth Scopes:

• r:awx_action:settings.account_details_view
• r:awx_action:balances_view
• w:awx_action:contact_management_edit
• w:awx_action:transfers_edit

To enable bill payments:

1. Check that the customer has sufficient funds in their account using the GET /api/v1/balances/current API endpoint
2. Create a Beneficiary for the Vendor with their payment details (e.g. bank account numbers), if you have not previously created one. Beneficiary records on Airwallex can be re-used across multiple Payouts. Call POST /api/v1/beneficiaries/create API to do this — note that the fields required to create a Beneficiary vary significantly across regions and destination bank account types, so you can use the POST /api/v1/beneficiary_api_schemas/generate API endpoint to obtain the correct schema for a given region and destination bank account type combination.
3. Once you have a valid Beneficiary, create the Payout with the amount of the bill to be paid by calling POST /api/v1/transfers/create API
4. Sometimes the Payout may be subject to additional review, in which case the status of the Payout will not be immediately successful. To obtain the most up-to-date status of the Payout, call GET /api/v1/transfers/{id} API with the Payout ID from the previous step.

Another common use case is allowing merchants or businesses to issue invoices and receive payments from their customers around the world via payment links. Airwallex supports payment methods ranging from international cards to popular local payment methods.

To enable payment acceptance via payments link, you will need the following OAuth Scopes:

• r:awx_action:payment_links_view
• w:awx_action:payment_links_edit

To generate a payment link for your invoices:

1. Create a payment link by calling POST /api/v1/pa/payment_links/create API. Our payment link supports two pricing options: fixed pricing where customer must pay the exact amount in the given currency and flexible payment where customer can pay in any of the supported currencies
2. Once a payment link is created, you can call POST /api/v1/pa/payment_links/{id}/notify_shopper API to have the payment link emailed to a specified email address.
3. To track payments, Airwallex sends a payment_intent.succeeded webhook that you can use for subsequent fulfillment and reconciliation purposes. Refer to the Notifications and Workflow Automation below for more information on setting up webhooks.
4. Check the status of the PaymentIntent by calling the GET /api/v1/pa/payment_intents/{id} API

Integrating Airwallex transactions directly into your accounting software streamlines the bookkeeping process by automating data entry. This integration minimises errors and saves valuable time that would otherwise be spent manually inputting transaction details.

To ingest Airwallex transactions, you will need the following OAuth Scopes:

• r:awx_action:balances_view

To build the transaction feed:

1. Read in balance history by calling GET /api/v1/balances/history API. Ensure that you add the header x-api-version in your API calls and set it to the latest version.

2. Please note that this API returns transaction data within a 7-day date range. If you attempt to query transactions beyond this range, you will receive a time_range_exceed error. To access the full transaction history, you can set the page parameter to 0 and use the page_before and page_after fields in the response to navigate through pages of transactions. Additionally, you may also adjust the page_size to return more transactions on a single page.

https://api.airwallex.com/api/v1/balances/history?page=0

3. Additionally, this API call includes reserve transactions that do not affect the account balance. Such transactions will not be visible in Airwallex Webapp wallet transactions or Balance Activity Report. You can filter out these transactions by using the transaction_type field and exclude the following transaction types:

• PAYMENT_RESERVE_HOLD
• PAYMENT_RESERVE_RELEASE
• HOLD
• HOLD_RELEASE
• ISSUING_AUTHORISATION_HOLD
• ISSUING_AUTHORISATION_RELEASE

4. Negate the amount for transactions of the type

• PAYMENT_RESERVE

Partners such as payment orchestrators can facilitate payment acceptance for their connected accounts through Airwallex. To build such an integration, you will need the following OAuth Scopes:

• w:awx_action:pa_edit
• r:awx_action:pa_view

You will also need to choose which integration type you would like to use. For payment orchestrators, we generally recommend either Native API or Embedded Elements, depending upon whether you are PCI-DSS compliant or not.

Prior to facilitating payments with any Airwallex merchant, please ensure that their account is connected and they have passed all KYC/KYB steps such that their account is active and the relevant payment methods are enabled on their account. A merchant’s enabled payment methods can be verified either through the webapp or through native API calls API.

Native API Integration

A Native API integration is permitted only for partners with PCI-DSS certification; a Report on Compliance (ROC) must be provided to enable this.

It’s essential that Airwallex is able to identify which partner is making native API calls on behalf of any merchant. Otherwise, the API calls may be blocked. We have two options for this: IP whitelisting and secure tokens. If you use a static outbound IP address, you should reach out to Airwallex to register those IP addresses as being whitelisted for your account. Otherwise, if you use a dynamic or unpredictable outbound IP address, you should reach out to Airwallex to request a secure token, which you would then need to include in your API requests going forward.

You will also need to integrate with 3DS. Airwallex recommends integrating with Airwallex 3DS in order to provide the best possible experience. However, for partners who must use external 3DS, external 3DS integrations are also supported . In addition to 3DS, we require that you implement device fingerprinting for fraud prevention.

To complete your Native API payment acceptance integration, please refer to the below documents and diagram.

AWX Native API Documentation

Payment Methods

Apple Pay Native API Documentation

Google Pay Native API Documentation

Embedded Elements Integration

For partners not integrating with Native API, Airwallex provides pre-built “Elements” that can be embedded into your experience with less effort. The Drop In Element provides a full-featured checkout module, which lets you accept multiple payment methods easily. For a more customized experience, you could choose instead to use Embedded Elements , such as the Card Element, Split Card Element, Apple Pay Button Element, and Google Pay Button Element, rather than an all-in-one solution. For further details on how to integrate, please refer to the below documents and diagrams:

Introduction to Drop In Element

Introduction to Embedded Elements

Introduction to Airwallex.js SDK

Payment Methods