Bill payments

Invoicing and payment links

Bank feed

Online payment acceptance

Integration guides

A quick introduction to the essential dev tools for building with Airwallex

Developer Essentials

Explore the flexibility and power of Airwallex APIs

Quickly and securely integrate with Airwallex products using Airwallex SDKs

SDKs

Learn how to receive push notifications via webhooks

Webhooks

Use Airwallex's sandbox environment to simulate transactions before going live

Sandbox environment

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`

![Bill payments OAuth interaction](//images.ctfassets.net/c3n7jozh84hr/2575GzVvLIXfJ1x4LPo3do/baa01e0fa3962ff050b09a145a5f57d5/image.png)

To enable bill payments:

1. Check that the customer has sufficient funds in their account using the GET [/api/v1/balances/current](/api#/Core_Resources/Balances/_api_v1_balances_current/get) 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#/Payouts/Beneficiaries/_api_v1_beneficiaries_create/post) 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#/Payouts/Beneficiaries/_api_v1_beneficiary_api_schemas_generate/post) 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](https://www.airwallex.com/docs/api#/Payouts/Transfers/_api_v1_transfers_create/post)
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}](https://www.airwallex.com/docs/api#/Payouts/Transfers/_api_v1_transfers__id_/get) 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`

![Invoicing diagram](//images.ctfassets.net/c3n7jozh84hr/5JaZ55YOP8rvNgKonYhfJy/c413d1af41c6a682a44d31d51f1b410a/image__5_.png)

To generate a payment link for your invoices:

1. Create a payment link by calling POST [/api/v1/pa/payment_links/create](/api#/Payment_Acceptance/Payment_Links/_api_v1_pa_payment_links_create/post). 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#/Payment_Acceptance/Payment_Links/_api_v1_pa_payment_links__id__notify_shopper/post) 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#/Payment_Acceptance/Payment_Intents/_api_v1_pa_payment_intents__id_/get)

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`

![Bank Feed Integration](//images.ctfassets.net/c3n7jozh84hr/PsQ27ToQAdHRLgkwOQwnS/aa2c5b71b1fdb288e3e9eb95a73e0b0e/image__1_.png)

To build the transaction feed:

1. Read in balance history by calling GET [/api/v1/balances/history](https://www.airwallex.com/docs/api#/Core_Resources/Balances/_api_v1_balances_history/get). 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 online 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`

On a case-by-case basis, partners who have good reasons why Oauth is not acceptable for their use-case may be approved to use API keys instead of Oauth for this purpose. Please reach out to partner-integration@airwallex.com if you require using API keys instead of Oauth.

You will also need to choose which [integration type](https://www.airwallex.com/docs/payments__online-payments-overview) 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](https://help.airwallex.com/hc/en-gb/articles/5898028587279-How-do-I-enable-or-disable-a-payment-method) or through [native API calls](https://www.airwallex.com/docs/api#/Payment_Acceptance/Config/_api_v1_pa_config_payment_method_types/get).

Regardless of the integration type you choose, please ensure you pass the following information to Airwallex during payment intent creation and confirmation in order to maximise success rates:
- Customer (email + customer name)
- Product information
- Shipping information
- Billing information

Further details on how to pass the above information is available [here](https://www.airwallex.com/docs/payments__risk-management__enhance-fraud-protection-with-comprehensive-payment-data).

Details on how to integrate with Native API and Embedded Elements are provided below.

__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. You can email partner-integration@airwallex.com with your Report on Compliance to get enabled for Native API access.

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. To identify yourself to Airwallex, you will need to populate a field called referrer_data.type within your API request with an Airwallex-provided value. Additionally, you will need to do one of the following:
- If you are using static IP addresses, get Airwallex to whitelist these IP addresses for native API access. Please note that these IP addresses must be specific to your company, and not shared across multiple companies (i.e. certain IP addresses provided by public cloud services).
- Alternatively, if you are using a unpredictable IP addresses, you will need to include an additional Airwallex-provided secure token in your API request.

To perform IP whitelisting, to obtain the secure token, or to obtain the referrer_data.type value, you can email partner-integration@airwallex.com.

You will also need to integrate with 3DS. Airwallex recommends [integrating with Airwallex 3DS](https://www.airwallex.com/docs/payments__native-api__3d-secure-authentication) in order to provide the best possible experience. However, for partners who must use external 3DS, external 3DS integrations are also [supported](https://www.airwallex.com/docs/payments__native-api__3d-secure-authentication__native-api-(for-api-versions-on-or-after-2024-06-14)#i'm-already-integrated-to-an-external-3ds-provider.-how-do-i-complete-a-airwallex-payment-using-this-provider--3_J67WtPqqLlp6srB5GuGmv). In addition to 3DS, we require that you [implement device fingerprinting](https://www.airwallex.com/docs/payments__native-api__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](https://www.airwallex.com/docs/payments__native-api)

[Payment Methods](https://www.airwallex.com/docs/payments__payment-methods-overview)

[Apple Pay Native API Documentation](https://www.airwallex.com/docs/payments__global__apple-pay__native-api)

[Google Pay Native API Documentation](https://www.airwallex.com/docs/payments__global__google-paytm__native-api)

![Native API](//images.ctfassets.net/c3n7jozh84hr/4HPNasVZxEgQjXdyt9RBeH/cfc8eb935a5122913cdb2c7e385d4233/nativeapi2.png)

__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](https://www.airwallex.com/docs/payments__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 more granular [Embedded Elements](https://www.airwallex.com/docs/payments__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](https://www.airwallex.com/docs/payments__drop-in-element)

[Introduction to Embedded Elements](https://www.airwallex.com/docs/payments__embedded-elements)

[Introduction to Airwallex.js SDK](https://www.airwallex.com/docs/developer-tools__sdks__airwallex.js)

[Payment Methods](https://www.airwallex.com/docs/payments__payment-methods-overview)

![Drop In Element](//images.ctfassets.net/c3n7jozh84hr/74HhsDfNdgXaJsFaadeVZU/3beddcf11780cbca2367c91f0faecf1b/dropin2.png)

![Embedded Elements](//images.ctfassets.net/c3n7jozh84hr/0xFCpE6n0FZmU1rYF29ef/dcdd7fe1d89766db2164ebb3e7c9064d/embedded2.png)

The following integration guides outline the scopes and necessary API calls essential for implementing typical use cases developed by our partners.

- [Bill payments](/developer-tools__integration-guides__bill-payments)
- [Invoicing and payment links](/developer-tools__integration-guides__invoicing-and-payment-links)
- [Bank feed](/developer-tools__integration-guides__bank-feed)
- [Online payment acceptance](/developer-tools__integration-guides__online-payment-acceptance)


docsLogo

Europe

Multi-Currency Pricing API

Viet Nam

United Kingdom

Verify a beneficiary account

Dedicated Account per Payment 

Desktop/Mobile Website Browser 

PromptPay

PayPal & Venmo Disputes

 Account

Balance

Billing

Charges

Connected Account Transfers

Connections

Conversions

Deposits

Direct debit payouts

Global Accounts

Issuing

Linked Accounts

Online Payments

Platform

 Transfers

Payload examples

Account capability

Account status

Funds Split

Online payments

PSP Agnostic

Transfers

Event types

Guest user checkout

Registered user checkout

Place a hold on a payment method

3D Secure authentication

Enhance fraud protection with comprehensive payment data

Device fingerprinting

Cancellations

Refunds

Network Tokenization

Card Account Updater

Error response codes

Native API

View connected accounts

Install Airwallex Online Payments app

View transactions

Handle RFIs

Connected Account Transfers (older versions)

Redirect from iOS Apps

Hosted Payment Page

Choose your payments solution

Embedded SCA component

Embedded Transaction RFI component

Embedded Payment Enablement RFI component

Embedded KYB component

Embedded KYC RFI component

Embedded KYC component

Embedded Tax Form component

 Embedded Beneficiary component

Embedded Transfer component

Google Pay Element

Desktop/Mobile Website Browser

Maxima

Lithuanian Banks

Perlas Terminals

Narvesen

Paysera

Latvian Banks

Customization options

Upgrade to Airwallex.js

Error codes

Airwallex.js

Estonian Banks

New Zealand (NZ_BECS_DEBIT)

Direct debit deposit error codes

Singapore (SG_EGIRO_DEBIT)

Hong Kong (HK_FPS_DEBIT)

Canada (CA_EFT_DEBIT)

Europe SEPA (EU_SEPA_DEBIT)

United Kingdom (GB_BACS_DEBIT)

United States (US_FEDWIRE_DEBIT)

United States (US_ACH_DEBIT)

Australia (AU_PAYTO_DEBIT)

Direct debit schemes and mandate requirements

Retrieve your deposits

Direct debit deposit statuses

Understanding direct debit flight times and funding limits

Add funds via direct debits from Linked Accounts

Australia (AU_BECS_DEBIT)

Linked Account statuses

Embedded Merchant Risk RFI component

Hosted Merchant Risk RFI flow

PayNow

Dedicated Account per Customer

Accept bank transfer payments

Bank transfer - BETA

Native Merchant Risk RFI API

Naver Pay recurring payments

Desktop Website Browser - Naver Pay

Mobile Website Browser - Naver Pay

Naver Pay - BETA

Install the Bigcommerce App

Enable and Configure Payment Methods

Multi-Channel Support

BigCommerce

Enable Embedded Klarna, Afterpay and Wechat

PayPal recurring payments

Desktop/Mobile Website Browser - PayPal

PayPal

Sandbox environment overview

Application fees

Transfer statuses (older versions)

Retrieve supported beneficiary banks

Using API and form schemas

Connected Account Console

Cash App Pay Disputes

Currency precision

Desktop/Mobile Website Browser - Cash App Pay

Cash App Pay - BETA

Dispute flow

Handle disputes on the Airwallex web app

Handle disputes using our APIs

Dispute response best practices

Pre-chargeback programs

Dispute notifications

Afterpay / Clearpay Disputes

Klarna Disputes

Disputes

Dispute Flow

Handling Disputes

Pakistan

Nepal

Chile

Bolivia

Tanzania, United Republic of

Powerful and flexible APIs to programmatically manage your money

Platform APIs

APIs and components to build your own global financial products.

Embedded Finance Use Cases

Programmatically create accounts and onboard customers

Connected Accounts icon

Programmatically create connected accounts for businesses and individuals, and enable them with rich financial capabilities.

Overview

Connected Accounts

How connected accounts work

Supported regions

Get started

Manage accounts

Move funds

Accounts icon

Open and manage global accounts at scale in 20+ currencies.

Accounts

Supported regions and currencies

Receive funds

Process payouts

Test and go live

Accept one-time and recurring payments, with like-for-like settlement for multiple currencies

PaymentsActive

PaymentsNormal

Accept payments from your customers around the world with cards and 160+ alternative payment methods. 