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/payments/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/payments/{payment_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