Native API
Overview
These are the steps to fully activate a payment method:
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.
Request to enable payment method capabilities on demand after KYC pass.
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.
(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
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
Response body
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
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
Response body
Step 3 Check capability status
GET /api/v1/account_capabilities/{capability_id}
- Description
- Available capability IDs
- payments_visa
- payments_mastercard
- Please refer to payment method list for the full list
- Available capability IDs
- Header
- x-on-behalf-of: $connected_account_open_id
Response body
Webhook: payment_method.enabled webhook
payload
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
Webhook: reserve_plan.updated webhook
Payload
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.
- 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
)
- Address line 1 should mandatorily have a house number (
- Primary contact details
- Contact email is mandatory (
primary_contact.email
) - Contact mobile number is mandatory (
primary_contact.mobile
)