Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Back to home
OverviewUnderstanding Payments for PlatformsChoose your Payments for Platforms solution
Use cases
Hold & convert funds
Connected accounts
Connected accounts overviewOnboard connected accounts
KYC and onboarding
Handle KYC RFI
KYB and onboarding
Embedded KYB componentHosted Onboarding Native API
Payment Method Onboarding Requirement
Handle Payment Enablement RFI
Onboard multiple connected accountsMove funds between accounts
Error codes

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.

  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

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

Response body

JSON

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

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

    • 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

Response body

JSON

Step 3 Check capability status

GET /api/v1/account_capabilities/{capability_id}

  • Description
    • Available capability IDs
  • Header
    • x-on-behalf-of: $connected_account_open_id

Response body

JSON

Webhook: payment_method.enabled webhook

payload

JSON

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

Webhook: reserve_plan.updated webhook

Payload

JSON

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)
  1. Primary contact details
  • Contact email is mandatory (primary_contact.email)
  • Contact mobile number is mandatory (primary_contact.mobile)
On this page