Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Embedded Finance
Global Treasury
Banking as a Service
Payments for Platforms
Developer Tools
Trust Center
Business Account Help Center
API Reference
Back to home
OverviewHow Airwallex Payouts work
Payout network
Use cases
Payouts
Batch transfers
Beneficiaries
Create beneficiariesValidate a beneficiaryRetrieve beneficiariesManage beneficiariesUsing API and form schemas
Embedded Beneficiary component
Payers
Errors
Test and go live
Older API versions

Using API and form schemas

When creating a payout, you can choose to:

  1. Specify the beneficiary_id of a previously saved beneficiary.
  2. Provide the beneficiary information directly in the request.

The former is recommended as it allows you to manage beneficiaries and create payouts more efficiently.

Learn on this page how you can incorporate Airwallex’s dynamic beneficiary schema into your product/system to collect beneficiary information accurately for creating beneficiaries and/or payouts via API.

Airwallex offers API schema and form schema for you to programmatically retrieve the required fields, validation rules and/or recommended UI components in JSON format, specific to the payout scenario.

You will need to build a generic response handler to parse the validation rules and recommended UI component definitions in the response and adopt them in your system/product. However, as all schema and field validation rules are maintained by Airwallex, once integrated there will be no further code changes needed on your end when there are updates.

See in the following table how they work:

API SchemaForm Schema
When to useYou would like to define the UI (user interface) components for collecting beneficiary information based on Airwallex’s schema and validation rules only.You would like to adopt the UI components proposed by Airwallex in addition to Airwallex’s schema and validation rules to collect beneficiary information.
How to useCall Get the API schema API endpoint. See more in Request parameters below.Call Get the form schema API endpoint. See more in Request parameters below.
What is returnedBeneficiary fields and their corresponding validation rules. You can choose to implement the exact rules on your product/system.Beneficiary fields and their corresponding validation rules, as well as UI (User Interface) components we propose for you to render each field on your product/system.

You can call the schema APIs to obtain the validation rules or render the payout UI each time when creating/updating beneficiaries/payouts. This approach ensures that you are always referring to the latest schema and helps you avoid validation errors due to schema updates.

Alternatively, you can choose to store the schema if you prefer to access them locally as you apply validation rules or render payout experiences. You will then need to update the cached schemas regularly (e.g. once a month) for any updates to our schemas.

Different schemas and validation rules may apply for different Airwallex accounts; therefore if you are a platform account, please call these endpoints on behalf of your connected accounts to retrieve the correct schemas and validation rules.

Request parameters

Call Get the API schema API or Get the form schema API to retrieve the corresponding schemas and validation rules based on the parameters provided:

  • bank_country_code: The 2-letter ISO 3166-2 country code of the beneficiary's bank.
  • account_currency: The 3-letter ISO 4217 currency code.
  • payment_method: The payment method for the payout (LOCAL or SWIFT)
  • local_clearing_system: The local clearing system for LOCAL payouts where applicable (a default value will apply when this parameter is not specified and payment_method is LOCAL). To learn more about supported local clearing systems, see Payout network.
  • entity_type: The type of the beneficiary, COMPANY (business) or PERSONAL (individual).

While all of the above parameters are needed for retrieving a specific beneficiary schema for the payout scenario, you can call the endpoints with none or some of the parameters for possible values accepted in the others. This is to support dynamic rendering of your product/system experience to narrow down to the specific schema and validation rules via multiple interactions with the schema APIs.

A 400 error SCHEMA_DEFINITION_NOT_FOUND will be returned in case of invalid or unsupported requests. If you are unsure which values are acceptable for each parameter, call the endpoint without any parameters to retrieve the possible values and retry again.

Example request

Shell

If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.

Response for API schema

A successful response returns the condition specified in the request and the fields containing the following parameters:

  • key: The name of the request parameter.
  • path: A hierarchical representation of the key using the parent objects up to the top-level parent.
  • required: Indicates whether the field is required for the given payout scenario.
  • rule: Validation rules for the field, including:
    • pattern: The acceptable value for this field, or a required format under regular expression.
    • type: The data type for the field.

Example response

JSON

Response for form schema

A successful response returns the condition specified in the request and the fields containing the following parameters:

  • enabled: Whether a field should be enabled for end users on the user interface.

  • field: An object containing attributes defining how each field can be rendered:

    • default: Recommended default prefilled value for this field.
    • description: Short description of the field to provide more context.
    • example: Example value of the field.
    • key: Name of the field per API request.
    • label: Name of the field to render on the UI.
    • placeholder: Placeholder text for the field if applicable.
    • refresh: Whether updating this field triggers a UI reload event.
    • tip: Additional information if prompted by mouse hover.
    • type: The type of UI component. Could be INPUT, SELECT, RADIO, or PAYMENT_METHOD.

    • option: An object containing possible values for this field. Parameters defining the UI components include description, label, and value (acceptable value to be used in the request). For the payment_method values specifically, the following parsable information will also be returned under option where applicable:

      transfer_limit with min/max objects, each composed of amount and currency; and

      flight_time with min/max values in ISO 8601 format (e.g. "max": "P3D", "min:"P0D" means 0-3 business days).

  • path: A hierarchical representation of the key using the parent objects up to the top-level parent.

  • required: Indicates whether the field is required for the given payout scenario.
  • rule: Validation rules for the field containing the following parameters:
    • pattern: The acceptable value for this field, or a required format under regular expression.
    • type: The data type for the field.

Example response

JSON
On this page
  • Request parameters
  • Response for API schema
  • Response for form schema