Native API

Overview

These are the steps to fully activate a payment method:

1. Provide store information using accounts API

   a. For new accounts, the platform can send the store information in the create account API.

   b. For existing accounts, the platform can send the store information through account amendment API.

2. Request to enable payment method capabilities on demand after KYC pass.

3. Polling or waiting for webhooks to check capability status until the capability status becomes ENABLED. The ENABLED status indicates that AIRWALLEX has activated the payment method and you can start transacting. When the capability status is PENDING, more information could be asked through RFI for the evaluation of Airwallex. When the capability status is DISABLED, you can find the detailed reasons in the reason_codes and reapply if applicable.

4. (Optional) Some customers might require reserves and you can use api or webhook to query the reserve terms.

Step 1-A Create account with store details

POST /api/v1/accounts/create

• Description
  • There is new field store_details in the account_details structure for business accounts.
  • store_details can be updated with the update API before submission. store_details applies to all versions.
• Here is a sample payload with version 2023-06-15. Please refer to store detail requirement for detailed requirements

JSON
1{
2    "account_details": {
3        "store_details": {
4            "cross_border_transaction_percent": "50.0",
5            "dispute_percent": "0.5",
6            "estimated_transaction_volume": {
7                "average_amount_per_transaction": "10000.0",
8                "currency": "USD",
9                "max_amount_per_transaction": "20000.0",
10                "monthly_transaction_amount": "500000.0"
11            },
12            "financial_statements": [
13                {
14                    "file_id": "Yzc5YzlhZDctMjVjMC00MTc3LTkyODMtNDJhYjRjMzllN2JjLHwsaG9uZ2tvbmcsfCxpbWFnZSAoMTApLnBuZ18xNjk0NDA1MjE0MjM2"
15                }
16            ],
17            "fulfillment_days": 5,
18            "industry_code": "ICCV3_041501",
19            "mcc": "0763",
20            "operating_models": [
21                "ONLINE_CHECKOUT",
22                "INVOICES_OR_CUSTOM_ORDER_LINKS",
23                "IN_PERSON"
24            ],
25            "payment_distribution": [
26                {
27                    "payment_type": "CARDS",
28                    "percentage": "50.0"
29                },
30                {
31                    "payment_type": "BANK_DIRECT_DEBIT",
32                    "percentage": "50.0"
33                }
34            ],
35            "refund_percent": "5",
36            "store_address": {
37                "address_line1": "Stree nowhere, build 2",
38                "country_code": "AU",
39                "postcode": "12389",
40                "state": "NSW",
41                "suburb": "Sydney"
42            },
43            "store_description": "i sell toys",
44            "store_name": "my stores",
45            "store_websites": [
46                {
47                    "url": "https://www.airwallex.com"
48                }
49            ]
50        },
51        "business_person_details": [
52            ...more fields
53        ],
54        "business_details": {
55      ...more fields
56         },
57        "legal_entity_type": "BUSINESS"
58    },
59    "customer_agreements": {
60        "agreed_to_data_usage": true,
61        "agreed_to_terms_and_conditions": true,
62        "opt_in_for_marketing": true
63    },
64    "primary_contact": {
65        "email": "[email protected]"
66    }
67}
68

Step 1-B Add store details - for existing accounts

POST /api/v1/account/amendments/create

• Description
  • Before enabling the payment method capabilities, the store details can be amended and the latest data can be obtained from the GET /api/v1/accounts/{id} API.
  • Before enabling the payment method capabilities, the status of the amendment will always be APPROVED.
  • Available amend target
    • account_details.store_details
  • Amendment status
    • PENDING
    • APPROVED
    • REJECTED
• Header
  • x-on-behalf-of: $connected_account_open_id

Request body

JSON
1{
2  "target": "account_details.store_details",
3  "store_details": {
4    "operating_models": [
5      "ONLINE_CHECKOUT",
6      "INVOICES_OR_CUSTOM_ORDER_LINKS",
7      "IN_PERSON"
8    ],
9    "store_name": "my store",
10    "store_websites": [{"url": "https://mystore.shopee.com"}],
11    "store_description": "I sell toys",
12    "industry_code": "ICCV3_041501",
13    "store_address": {
14      "address_line1": "Stree nowhere, build 2",
15      "country_code": "AU",
16      "postcode": "12389",
17      "state": "NSW",
18      "suburb": "Sydney"
19    },
20    "estimated_transaction_volume": {
21      "currency": "USD",
22      "average_amount_per_transaction": "10000.0",
23      "max_amount_per_transaction": "20000.0",
24      "monthly_transaction_amount": "500000.0"
25    },
26    "cross_border_transaction_percent": "50.0",
27    "fulfillment_days": 5,
28    "payment_distribution": [
29      {
30        "payment_type": "CARDS",
31        "percentage": "50.0"
32      },
33      {
34        "payment_type": "BANK_DIRECT_DEBIT",
35        "percentage": "50.0"
36      }
37    ],
38    "dispute_percent": "0.5",
39    "refund_percent": "5.0",
40    "mcc": "0763",
41    "financial_statements": [
42      {
43        "file_id": "MzkwZjI5OGMtYTc5YS00ZDFkLWFjYzYtYjY1NjM2ODg4YmFiLHwsLHws5oiq5bGPMjAyMy0wNC0yNSAxNy4xNC4yMS5wbmdfMTY4NjE5NTk1NTI4Mg"
44      }
45    ]
46  }
47}

Response body

JSON
1{
2  "id": "ab221d5e-493f-4898-af21-9c2ca4e64016",
3  "status": "SUCCESS",
4  "target": "store_details",
5  "store_details": {
6    "operating_models": [
7      "ONLINE_CHECKOUT",
8      "INVOICES_OR_CUSTOM_ORDER_LINKS",
9      "IN_PERSON"
10    ],
11    "store_name": "my store",
12  "store_websites": [{"url": "https://mystore.shopee.com"}],
13    "store_description": "i sell toys",
14    "industry_code": "ICCV3_041501",
15    "store_address": {
16      "address_line1": "Stree nowhere, build 2",
17      "country_code": "AU",
18      "postcode": "12389",
19      "state": "NSW",
20      "suburb": "Sydney"
21    },
22    "estimated_transaction_volume": {
23      "currency": "USD",
24      "average_amount_per_transaction": "10000.0",
25      "max_amount_per_transaction": "20000.0",
26      "monthly_transaction_amount": "500000.0"
27    },
28    "cross_border_transaction_percent": "50.0",
29    "fulfillment_days": 5,
30    "payment_distribution": [
31      {
32        "payment_type": "CARDS",
33        "percentage": "50.0"
34      },
35      {
36        "payment_type": "BANK_DIRECT_DEBIT",
37        "percentage": "50.0"
38      }
39    ],
40    "dispute_percent": "0.5",
41    "refund_percent": "5.0",
42  "mcc": "0763",
43    "financial_statements": [
44      {
45        "file_id": "MzkwZjI5OGMtYTc5YS00ZDFkLWFjYzYtYjY1NjM2ODg4YmFiLHwsLHws5oiq5bGPMjAyMy0wNC0yNSAxNy4xNC4yMS5wbmdfMTY4NjE5NTk1NTI4Mg"
46      }
47    ]
48  }
49}
50

GET /api/v1/account/amendments/{amendment_id}

• Description
  • Get the amendment details of past amendments.
• Header
  • x-on-behalf-of: $connected_account_open_id

Response body

JSON
1{
2  "id": "ab221d5e-493f-4898-af21-9c2ca4e64016",
3  "status": "SUCCESS",
4  "target": "store_details",
5  "store_details": {
6    "operating_models": [
7      "ONLINE_CHECKOUT",
8      "INVOICES_OR_CUSTOM_ORDER_LINKS",
9      "IN_PERSON"
10    ],
11    "store_name": "my store",
12  "store_websites": [{"url": "https://mystore.shopee.com"}],
13    "store_description": "i sell toys",
14    "industry_code": "ICCV3_041501",
15    "store_address": {
16      "address_line1": "Stree nowhere, build 2",
17      "country_code": "AU",
18      "postcode": "12389",
19      "state": "NSW",
20      "suburb": "Sydney"
21    },
22    "estimated_transaction_volume": {
23      "currency": "USD",
24      "average_amount_per_transaction": "10000.0",
25      "max_amount_per_transaction": "20000.0",
26      "monthly_transaction_amount": "500000.0"
27    },
28    "cross_border_transaction_percent": "50.0",
29    "fulfillment_days": 5,
30    "payment_distribution": [
31      {
32        "payment_type": "CARDS",
33        "percentage": "50.0"
34      },
35      {
36        "payment_type": "BANK_DIRECT_DEBIT",
37        "percentage": "50.0"
38      }
39    ],
40    "dispute_percent": "0.5",
41    "refund_percent": "5.0",
42  "mcc": "0763",
43    "financial_statements": [
44      {
45        "file_id": "MzkwZjI5OGMtYTc5YS00ZDFkLWFjYzYtYjY1NjM2ODg4YmFiLHwsLHws5oiq5bGPMjAyMy0wNC0yNSAxNy4xNC4yMS5wbmdfMTY4NjE5NTk1NTI4Mg"
46      }
47    ]
48  }
49}
50

Step 2 Enable payment method capability

This step is to apply for both the account capability to use payment methods and also the payment method activation for the store. When the capabilities are granted, the corresponding payment methods are activated.

POST /api/v1/account_capabilities/{capability_id}/enable

• Description

  • Available capability IDs

    • payments_visa
    • payments_mastercard
    • Please refer to payment method list for the full list

  • Capability status

    • PENDING
    • ENABLED
    • DISABLED If there are multiple capabilities to be enabled, the request should be sent sequentially and those capabilities will be processed together.
• Header
  • x-on-behalf-of: $connected_account_open_id

Request body

JSON
1{
2  "id": "payments_jcb"
3}

Response body

JSON
1{
2  "id": "payments_jcb",
3  "status": "PENDING",
4  "updated_at": "2023-04-01T11:25:39+0000",
5  "comment": "Processing"
6}
7

Step 3 Check capability status

Check capability status by Get Capability API API

• Description
  • Available capability IDs
    • payments_visa
    • payments_mastercard
    • Please refer to payment method list for the full list
• Header
  • x-on-behalf-of: $connected_account_open_id

Response body

JSON
1{
2  "id": "payments_jcb",
3  "status": "PENDING",
4  "updated_at": "2023-04-01T11:25:39+0000",
5  "comment": "Processing"
6}
7

Webhook: account_capability.enabled webhook

payload

JSON
1{
2   "account_id": "acct_TOslkS7-MnyXlQuV8Lb4ag",
3   "data": {
4      "id": "payments_jcb"
5      "status": "ENABLED",
6      "updated_at": "2023-03-31T16:08:02+0000"
7      "comment": "capability has been enabled" 
8   },
9   "id": "86b69f91-06f0-3fe8-8faf-4de58954ca8e",
10   "name": "account_capability.enabled",
11   "created_at": "2023-03-31T16:08:02+0000"
12}
13

For disabled payment methods, you can find the detailed reasons in the reason_codes

Response body

JSON
1{
2    "comment": "Please review the rejection reason and update your website accordingly before resubmitting.",
3    "details": {
4        "reason_codes": [
5            "WEBSITE_LEGAL_NAME_MISMATCH",
6            "WEBSITE_NO_CONTACT_INFO",
7            "WEBSITE_INDUSTRY_MISMATCH",
8            "WEBSITE_REGISTRATION_ADDRESS_MISMATCH",
9            "WEBSITE_NO_CHECKOUT"
10        ]
11    },
12    "id": "payments_go_pay",
13    "status": "DISABLED",
14    "updated_at": "2025-05-22T03:12:31+0000"
15}

Reason_codes details

Step 4 Check reserve terms

Some customers might require reserves and you can use api or webhook to query the reserve terms. You can learn more about reserve here

GET /api/v1/pa/config/reserve_plan

• Header
  • x-on-behalf-of: $connected_account_open_id

Response body

JSON
1{
2  "type": "DELAYED_ROLLING",
3  "delayed_rolling": {
4 "delay_in_days": 2,
5 "rolling_window_in_days": 5,
6 "rolling_percentage": 15
7  }
8}

Webhook: reserve_plan.updated webhook

Payload

JSON
1{
2  "id": "0a963b8c-c292-48b0-bc96-a424a3cfea6f",
3  "name": "reserve_plan.updated",
4  "account_id": "acct_e_2wbiZ3Mx-ynlX-7Qidbg",
5  "data": {},
6  "created_at": "2024-04-11T07:29:36+0000",
7  "version": "2023-03-31"
8}

Additional Requirement for US Merchants

If your merchant is registered in the US, you'll need to submit the following additional requirements in account details to use payments.

1. US person information (account_details.business_person_details)

• At least one US person with SSN or ITIN is required (account_details.business_person_details.identifications.primary.tax_id.type)
• The US person can be one of the following role: AUTHORISED_PERSON, BENEFICIAL_OWNER, CONTROLLING_PERSON (account_details.business_person_details.roles)
• Date of Birth is mandatory (account_details.business_person_details.date_of_birth)
• Full address of the US person should be provided, including:
  • Address line 1 should mandatorily have a house number (account_details.business_person_details.residential_address.address_line1)
  • Postal code is mandatory (account_details.business_person_details.residential_address.postcode)
  • Two-letter state code is mandatory if it's a US state e.g. CA for California (account_details.business_person_details.residential_address.state)

2. Primary contact details

• Contact email is mandatory (primary_contact.email)
• Contact mobile number is mandatory (primary_contact.mobile)