Using API and form schemas
When creating a payout, you can choose to:
- Specify the
beneficiary_idof a previously saved beneficiary. - Provide the
beneficiaryinformation 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 Schema | Form Schema | |
|---|---|---|
| When to use | You 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 use | Call 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 returned | Beneficiary 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.transfer_method: The transfer method for the payout (LOCALorSWIFT)local_clearing_system: The local clearing system forLOCALpayouts where applicable (a default value will apply when this parameter is not specified andtransfer_methodisLOCAL). To learn more about supported local clearing systems, see Payout network.entity_type: The type of the beneficiary,COMPANY(business) orPERSONAL(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
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
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 beINPUT,SELECT,RADIO, orTRANSFER_METHOD.option: An object containing possible values for this field. Parameters defining the UI components includedescription,label, andvalue(acceptable value to be used in the request). For thetransfer_methodvalues specifically, the following parsable information will also be returned underoptionwhere applicable:transfer_limitwithmin/maxobjects, each composed ofamountandcurrency; andflight_timewithmin/maxvalues 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.