Guest user checkout

Registered user checkout

Place a hold on a payment method

Cancellations

Refunds

Native API

3D Secure authentication

Network Tokenization

Device fingerprinting

Multi-currency pricing

Error response codes

A quick introduction to building with Airwallex APIs

Quickstart

Explore our comprehensive reference to integrate with Airwallex API endpoints

API Reference

Learn how to receive push notifications via webhooks

Webhooks

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 __7 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. It is best suited if you are PCI-DSS compliant and want to leverage that capability to provide a customized checkout experience to your shoppers.

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

Embedded KYC RFI component

Hosted KYC RFI flow

Native KYC RFI API

Handle KYC RFI

Handle KYC Request for Information (RFI)

Hosted Transaction RFI flow

Embedded Transaction RFI component

Native Transaction RFI API

Handle Transaction RFI

Handle Transaction Request for Information (RFI)

RFI (Request for Information)

Native Cardholder RFI API

Handle Cardholder RFI

Handle Cardholder Request for Information (RFI)

Cardholder types

Cardholder statuses

Create cardholders

Desktop/Mobile Website Browser - Klarna

Dispute Management - Klarna

Extra Merchant Data (EMD) - Klarna

Klarna

Dispute Flow

Handling Disputes

Dispute Notifications

Pay with QR Code (Desktop Website Browser) - WeChat Pay

Mobile App - WeChat Pay 

WeChat Official Account - WeChat Pay

WeChat Mini Program - WeChat Pay

Mobile Browser (H5) - WeChat Pay

Customs Declaration - WeChat Pay

Funds Split - WeChat Pay

WeChat Pay

Funds reconciliation

Pay with QR Code (Desktop Website Browser) - Touch 'n Go

Mobile Website Browser - Touch 'n Go

Mobile App - Touch 'n Go

Touch 'n Go

Pay with QR Code (Desktop Website Browser) - Rabbit LINE Pay

Mobile Website Browser - Rabbit LINE Pay

Mobile App - Rabbit Line Pay

Rabbit LINE Pay

Pay with QR Code (Desktop Website Browser) - GCash

Mobile Website Browser - GCash

Mobile App - GCash

GCash

Pay with QR Code (Desktop Website Browser) - DANA

Mobile Website Browser - DANA

Mobile App - DANA

DANA

Pay with QR Code (Desktop Website Browser) - TrueMoney

Mobile Website Browser - TrueMoney

Mobile App - TrueMoney

TrueMoney

Pay with QR Code (Desktop Website Browser) - Kakao Pay

Mobile Website Browser - Kakao Pay

Mobile App - Kakao Pay

Kakao Pay

Mobile App - Alipay CN

Mobile Website Browser - Alipay CN

Mini Program - Alipay CN

Customs Declaration - Alipay CN

Pay with QR Code (Desktop Website Browser) - Alipay CN

Alipay CN

Mobile App - Alipay HK

Mobile Website Browser - Alipay HK

Pay with QR Code (Desktop Website Browser) - Alipay HK

Alipay HK

Transaction failure reasons

Physical and digital cards (older API versions)

Create individual cards (older API versions)

Card statuses

Create a card (older API versions)

Physical and digital cards

Create commercial cards

Create consumer cards

Whitelabel card offering

Create cards

Choose your issuing solution

Supported card programs

Fund your issuing balance (older API versions)

Choose your issuing solution (older API versions)

Supported card types (older API versions)

Secure iframes

Retrieve sensitive card details

Fund your issuing balance

Platform issuing infrastructure for businesses

Consumer payouts via cards

Batch transfers

Payout statuses

Generate a confirmation letter

Simulate payout status transition

Create a payout

 Payout error codes

Batch transfer error codes

Manage approvals for batch transfers

Manage batch transfers

Retrieve batch transfers

Batch transfer statuses

Create a batch transfer

Issuing

Integration guide

Powerful and flexible APIs to programmatically manage your money

Core API

APIs and components to build your own global financial products

Embedded Finance

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. 

Overview

Payments

Choose your payments solution

Get started with payments

Online payments

Payment Links

Invoice integrations

Manage payments

Payment methods

Test and go live

Troubleshooting

Access interbank FX rates and intelligently manage currency risk

FXActive

FXNormal

Access interbank FX rates and programmatically manage currency risk.

Transactional FX

How Transactional FX works

Supported regions and currencies

Funding and settlement models

Use Cases

Get started

Amendments

Programmatically make cost effective, fast and secure global payouts 

PayoutsActive

PayoutsNormal

Programmatically make cost-effective, fast and secure payouts across the globe.

Payouts

How Airwallex Payouts work

Payout network

Use cases

Beneficiaries

Payers

Errors

Older API versions

Issue and manage multi-currency cards at scale, while reducing international transaction and FX fees

IssuingActive

IssuingNormal