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 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).
