Guest user checkout

Registered user checkout

Place a hold on a payment method

Cancellations

Refunds

Native API (For API versions on or after 2024-06-14)

Native API (For API versions before 2024-06-14)

3D Secure authentication

Network Tokenization

Device fingerprinting

Multi-currency pricing

Error response codes

Native API

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 demo environment to simulate transactions before going live

Demo environment

One-off or single payments help you to complete your checkout process when the Buyer is present and active in your web shop. In this scenario the Buyer will provide his card details as well as all the ancillary information required.

 1. Create a payment intent on your server with currency and amount you want to charge from your buyer using `POST/api/v1/pa/payment_intents/create`. You will receive the payment methods available as well as the next action to be performed.

Request:
```curl
curl https://pci-api.airwallex.com/api/v1/pa/payment_intents/create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_bearer_token \
  -d '{
    "request_id": "ed11e38a-7234-11ea-aa94-7fd44ffd1b89",
    "amount": 100.0,
    "currency": "CNY",
    "merchant_order_id":"{{$guid}}"
  }'
```
Response:
```json
{
    "id": "int_gECH4yeBzr50vOYFtzNyIsSW9e8",
    "request_id": "95527c7f-88d9-44c2-ba01-15886323c102",
    "amount": 100.0,
    "currency": "CNY",
    "merchant_order_id": "d45fe031-ac74-4347-b2db-00cb3528adca",
    "status": "REQUIRES_PAYMENT_METHOD",
    "captured_amount": 0,
    "created_at": "2020-06-21T05:23:25+0000",
    "updated_at": "2020-06-21T05:23:25+0000",
    "available_payment_method_types": [
        "card",
        "wechatpay"
    ],
    "client_secret": "your_client_secret"
}
```
 2. Use `POST/api/v1/pa/payment_intents/{id}/confirm`endpoint to submit the outstanding payment method details and request the authorization for a given payment.

Request:
```curl
curl -X POST \
  https://pci-api.airwallex.com/api/v1/pa/payment_intents/int_kaAB2ImTzoHeHG8TAzNtdr17x7C/confirm \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_bearer_token' \
  -d '{
  "request_id": "ed11e38a-7234-11ea-aa94-7fd44ffd1b81",
  "payment_method": {
        "type": "card",
        "card": {
          "number": "4012000300001003",
          "expiry_month": "01",
          "expiry_year": "2023",  
          "cvc": "123",
          "name": "Adam"
        }
    }
}'
```
Response:
```json
{
    "id": "int_jawNeudBz9ej5QqZgzGLekx0hQx",
    "request_id": "cb79c939-890a-418f-ab92-feb48d829771",
    "amount": 100.0,
    "currency": "HKD",
    "status": "REQUIRES_CAPTURE",
    "captured_amount": 0,
    "latest_payment_attempt": {
        "id": "att_tZsIgRiVztQSbVGd6zGLekx0hQx",
        "amount": 100.0,
        "payment_method": {
            "id": "mtd_o2DDW9rQc44PguUMiLGgisjkofB",
            "type": "card",
            "card": {
                "expiry_month": "01",
                "expiry_year": "2023",
                "name": "Adam",
                "bin": "401200",
                "last4": "1003",
                "brand": "visa",
                "issuer_country_code": "RU",
                "card_type": "credit",
                "fingerprint": "J9DRkJWyWE+YkjNiE0ogMiAtSIA=",
                "cvc_check": "unknown",
                "avs_check": "unknown"
            },
            "status": "VERIFIED",
            "created_at": "2020-06-21T05:52:48+0000",
            "updated_at": "2020-06-21T05:52:48+0000"
        },
        "status": "AUTHORIZED",
        "provider_original_response_code": "00",
        "authorization_code": "434929",
        "captured_amount": 0,
        "refunded_amount": 0,
        "created_at": "2020-06-21T05:52:49+0000",
        "updated_at": "2020-06-21T05:52:52+0000",
        "authentication_data": {
            "ds_data": {},
            "fraud_data": {
                "action": "ACCEPT",
                "score": "-1"
            },
            "avs_result": "U",
            "cvc_result": "U"
        }
    },
    "created_at": "2020-06-21T05:52:06+0000",
    "updated_at": "2020-06-21T05:52:52+0000"
}
```
If you received the status AUTHORIZED or SUCCEEDED (only if you are auto capturing) your payment is completed and you can release the goods to your Buyer.


You must follow the Capture use case detailed later to complete your transaction. If you forget to capture you will not receive any funds

Note

When capturing a Stored Credential for the first time

When initiating a subsequent transaction using a stored credential

Error Cases

When you create a payment, you can place a hold on an eligible payment method to reserve the funds for a few days and capture them later. The payment will stay in “Authorized” status during this period. 

Authorization helps guarantee the payment amount by holding it on the customer’s payment method. A typical use case is that hotels would normally ask the guest to authorize a deposit at  arrival to cover any potential additional charges and then capture the actual charges during checkout. During the whole stay, the funds will be held on the guest’s credit card.

You need to capture the funds before the authorization expires. You can capture less than the original amount, but cannot capture more. If the authorization expires before you capture the funds, the funds are released and the payment status changes to “Cancelled”. 

Please note that placing a hold is currently only supported for cards (including Apple Pay and Google Pay) and Klarna payment methods and the authorization expiry window differs by payment method:
- Card payments: By default the authorization expires in __5 days__. You can request extended authorization time-periods for the following cases (see more details in step 2):
  - Visa: Up to __31 days__ for cruise, lodging, or vehicle rental businesses
  - MasterCard: __30 days__ for all businesses
- Klarna: __28 days__ for all businesses

Step 1: Define the capture mode of your payment

(Optional) Step 2: Request extended authorization window

Step 3: Capture the funds

(Optional) Cancel the payment

You will cancel a payment intent when you initially performed a one-off payment but you did not capture it (either automatically or explicitly). A cancellation enables you to release the funds you had initially blocked on the Buyer's payment instrument and can only be applied to payment methods that require a capture operation to succeed.


Have you cancelled a payment but your Buyer still informs you that he sees a hold in his bank account? Do not worry, this is normal. You should double check you payment intent is successfully cancelled and inform your Buyer. The issuer bank will release the funds in the coming days.

You need to follow the below process:

 1. Use the `POST/api/v1/pa/payment_intents/{id}/cancel` endpoint to cancel a payment intent. The full amount of the intent will be cancelled, a cancellation reason can be provided. You will receive a synchronous response to inform you the request has been taken into account.

```curl
curl -X POST \
  https://pci-api.airwallex.com/api/v1/pa/payment_intents/int_tkZsvKMHzf37yTFqlztZ5NYEAvD/cancel \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_bearer_token' \
  -d '{
  "request_id": "285ecfc8-4c53-4543-8b9b-87d75e8666b9"
}'
```

```curl
{
    "id": "int_tWFe5PBQz9msmRCegzuZoUJcE49",
    "request_id": "c2e5204e-4f1b-402f-b58a-249f2ef34ee1",
    "amount": 100.0,
    "currency": "HKD",
    "merchant_order_id": "f488663a-d610-4f22-83ba-64202d7d76cc",
    "status": "CANCELLED",
    "captured_amount": 0,
    "created_at": "2020-06-28T10:11:49+0000",
    "updated_at": "2020-06-28T10:12:01+0000",
    "cancelled_at": "2020-06-28T10:12:01+0000"
}
```
 2. After we have successfully processed your cancellation, we will send you a webhook notification to inform you about the cancellation result.


You may refund a Payment Intent that your buyer has paid for before at any point after it has been successfully captured. This enables you to return the funds to your buyer

Have you received an RFI (or Request for Information) for a specific transaction or your Buyer has issued complaints about your product? You can use a Refund to avoid costly chargebacks.
Have you already received a chargeback for a specific intent? In this case note that the chargeback amount has been already deduced from your balance and returned to the Buyer by the Issuer Bank.

In order to perform a refund you have several options, either one partial refund, multiple partial refunds or one full refund are possible. You are not allowed to refund more funds that you initially collected from your buyer.

You need to follow the below process:

 3. Use the `POST /api/v1/pa/refunds/create` endpoint to make a refund. Provide the payment intent you are refunding, the reason and the amount (if not the full amount). You will receive a synchronous response to inform you the request has been taken into account.
```curl
curl -X POST \
  https://pci-api.airwallex.com/api/v1/pa/refunds/create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_bearer_token' \
  -d '{
  "payment_attempt_id": "{{payment_attempt_id}}",
  "reason": "customer requested",
  "request_id": "{{$guid}}"
}'

```
```curl
{
    "id": "rfd_daLxZ7dkzlayAqhQqzsgNoEfPhs",
    "request_id": "fbb30283-eec7-45ca-8d98-cd18e1c70a03",
    "payment_intent_id": "int_762cmJuYzpBmfpF89zsgNoEfPhs",
    "payment_attempt_id": "att_k8Q6nMOXznIQyfUlizsgNoEfPhs",
    "amount": 49.12,
    "currency": "HKD",
    "reason": "Return good",
    "status": "RECEIVED",
    "created_at": "2020-06-28T10:14:14+0000",
    "updated_at": "2020-06-28T10:14:14+0000"
}
```
 4. After we have successfully processed your refund, we will send you a webhook notification to inform you about the refund result.


3-Domain Secure™ (3D Secure or 3DS) authentication provides an additional layer of security by protecting you against fraud when you accept card payments online.  It requires shoppers to complete a verification step with the card issuer when paying, thereby shifting the liability for fraudulent card payments from you to the issuer in case of disputes. Airwallex supports 3DS for all card schemes that you can use to accept payments, namely Mastercard (Mastercard Identity Check), Visa (Visa Secure), and UnionPay. 

To provide an optimal 3DS experience to your shopper regardless of the interface (mobile app or website), Airwallex offers a fully-integrated 3DS solution supporting both 3DS 1 and 3DS 2.

* 3DS 1 is the original 3DS version that redirects shoppers to the card issuer’s site for authentication, for example, by entering a password or a code sent to their phone.

* 3DS 2 is the new version designed to enhance security in online purchases while providing frictionless checkouts to shoppers who are considered low risk by the card issuer. The issuer determines the risk based on the shopper information available during verification. When additional information is required to verify the shopper, the issuer presents a challenge to the shopper, for example, entering a code sent to their phone. The frictionless flow is attractive to shoppers and provides increased checkout conversion rates.

Airwallex always attempts 3DS 2 (if supported by the issuer and the card) and falls back to 3DS 1 only when 3DS 2 is not available.  Rest assured that your shopper will be offered the most suitable 3DS experience (frictionless or challenge) based on the card issuer by always keeping the shopper’s checkout conversion in mind.

![3DS1-3DS2](//images.ctfassets.net/c3n7jozh84hr/3JcxptE9Fg0jcLvmKz6Qk7/1f5fbc62df404e8ac37441a80be6a6e6/3DS2_1.png)


Integration options

What is a network token?

Why should a business use network token?

How to use network tokenization?

FAQs

Device fingerprinting uniquely tracks and identifies devices used for transacting on your shopping site, increasing your protection from fraud. 

Airwallex supports device fingerprinting on your Native API integration using Airwallex’s device fingerprint JavaScript. Once loaded into your shopping site, the script collects the shopper’s browser, screen, device, and interaction data and sends it to Airwallex. Rest assured that Airwallex collects, stores, and uses this data in compliance with PCI-DSS & GDPR. 

Follow this step-by-step guide to implement device fingerprinting on your existing Native API integration. 

Step 1: Add the script to your shopping site

Step 2: Add a unique session ID

Step 3: Send the session ID when you confirm the PaymentIntent

Multi-currency Pricing - MCP

Integrating with MCP

Airwallex uses conventional HTTP response codes to indicate the success or failure of an API request.


HTTP response codes and description

Error response structure

Error codes for HTTP response code 400

Error codes for HTTP response codes 401, 404 and 500

Error response examples

Airwallex's native API integration allows you to handle 100% of the interactions between your application's frontend and backend. Native API is best suited when you would like to provide a highly customized checkout experience to your shoppers. To be eligible for native API integration, a merchant must be PCI-DSS ROC compliant and undergo an Airwallex review. Contact your Airwallex Account Manager if you need guidance on how to become PCI-DSS  compliant. To learn more about PCI-DSS and the application process, refer to the [related help article](https://help.airwallex.com/hc/en-gb/articles/4406125912473-I-have-questions-about-PCI-DSS). 

Merchants who do not meet the eligibility requirements may consider [alternate integration options](/payments__online-payments-overview).

### Versioning

Airwallex uses [versioning](/api#/Versioning) to improve our API without impacting existing integrations. In this guide, the API examples as well as the notification event types are all presented in the latest version. For older versions, please refer to our [official API documentation](https://www.airwallex.com/docs/api).

__How do I choose the version?__

You may specify the version per API call by setting the __x-api-version__ header. However, in most cases you should rely on the configured version in your account. Overriding version by header is designed for testing and migrating to a new version. 

For webhook notifications, you may only specify the expected event version during the webhook creation. For more information, see [Listen for webhook events](/developer-tools__listen-for-webhook-events).


docsLogo

Retrieve supported beneficiary banks

Error codes

7-Eleven

Alipay CN

Alipay HK

Atome

Boost

DANA

DOKU Wallet

Dragonpay

DuitNow

E.SUN (Taiwan ATM & Internet banking)

GCash

GoPay

GrabPay - Malaysia

GrabPay - Singapore

Indonesian Bank Transfer

Indonesian Convenience Stores - BETA

Jenius Pay

Kakao Pay

Kiosk Payments

Konbini

Korean Local Cards - BETA

Laybuy by Klarna

LinkAja

Naver Pay - BETA

Pay-easy

Payco - BETA

PayNow

Philippines Online Banking

PromptPay

Rabbit LINE Pay

Samsung Pay - BETA

ShopeePay

Taiwan Convenience Stores

Tesco Lotus

Thailand Online Banking

Toss Pay - BETA

Touch 'n Go

TrueMoney

WeChat Pay

Zip - BETA

APAC

View connected accounts

Handle RFIs

Connected Account Console (Beta)

Getting Started

Install the Airwallex Apple Pay Payments App

Install the Airwallex Google Pay Payments App

Install Airwallex Card Payments app

Install Airwallex Online Payments App

Install Airwallex Klarna Payments App

Install Airwallex Afterpay Payments App

Shopline

Install the Magento plugin

Enable and Configure Payment Methods

View and Manage Transactions

Advanced Configuration

Magento

Integration guide

Accept bank transfer payments

Bank transfer - BETA

Upgrade from Payouts Web SDK

Upgrade from Payment Elements SDK

Upgrade to Airwallex.js

Customization options

Airwallex.js

Cash App Pay - BETA

ACH Direct Debit - BETA

 EFT Pre-Authorized Debit - BETA

 SPEI - BETA

Venmo - BETA

PIX - BETA

North America & LATAM

Cards

Airwallex Pay

Apple Pay

Google Pay™

Klarna

Afterpay / Clearpay

PayPal

Skrill

Global

Extra Merchant Data (EMD) - Klarna

Desktop/Mobile Website Browser

Transaction limits

Blocked Transaction Usage Scopes

Authorization controls

Enable Native Credit/Debit Cards

Enable Apple Pay (Express Checkout)

Enable Google Pay (Express Checkout)

Automatic Currency Conversion

Error codes (older versions)

Batch transfer webhooks (older versions)

Batch Transfers

Batch transfer error codes

Transfers

Provide Fraud Feedback

Install Airwallex Online Payments app

Enable MOTO Payments

Handle Overcaptures

Install Airwallex Sales Order App

Shopify

Dispute your direct debit payouts

Transaction Lifecycle

Issuing

Online payments overview

Hosted Payment Page

Payment Links overview

Connected Account Console (Beta) overview

Embedded KYC RFI component

Hosted KYC RFI flow

Native KYC RFI API

Handle KYC RFI

Review direct debit mandate requirements

South Africa

United States

Failure reasons

Retrieve physical card delivery details

Integration checklist

Manage your direct debit payout mandates

Manage your direct debit payouts

Direct debit payout statuses

Authorize direct debit payouts

Retrieve your deposits

Supported regions and currencies

Overview

Accounts

Move funds between accounts

Embedded Transaction RFI component

Hosted Transaction RFI flow

Native Transaction RFI API

Handle Transaction RFI

Embedded Payment Enablement RFI component

Hosted Payment Enablement RFI flow

Native Payment Enablement RFI API

Handle Payment Enablement RFI

Embedded KYB component

Hosted Onboarding 

Payment Method Onboarding Requirement

KYB and onboarding