Create beneficiaries

Call Create a new beneficiary API to save and manage beneficiaries that you can use for creating payouts using beneficiary_id.

Refer to the dynamic schema API for precise field requirements specific to the intended payout scenario. If you specify a parameter that is either not required or not on the full schema, it will be ignored and removed from the response. Please find below further considerations on some of the required parameters:

• beneficiary.type: Specify whether the beneficiary type is a BANK_ACCOUNT or a DIGITAL_WALLET (including Airwallex Pay). The value will default to BANK_ACCOUNT if not specified.
• beneficiary.bank_details: required beneficiary bank account details parameters will vary according to the specified payout scenario. Please refer to dynamic schema API or call Get the API schema API to obtain the corresponding parameter requirements.
• beneficiary.digital_wallet: Required beneficiary digital wallet parameters will vary according to the specified digital wallet provider. Please refer to dynamic schema API or call Get the API schema API to obtain the corresponding parameter requirements.
• beneficiary.address: required address parameters such as street_address, city, state and postcode will vary according to the specified address country. Please refer to dynamic schema API or call Get the API schema API to obtain the corresponding parameter requirements. The street_address must not be a P.O. box address.
• beneficiary.entity_type: Specify whether the beneficiary is an individual (PERSONAL) or a business (COMPANY).
• beneficiary.transfer_methods: Specify SWIFT to create an international SWIFT payout; or LOCAL to create a payout via the local clearing system, which is faster and more cost-effective. See Payout network for supported transfer methods by countries/regions and currencies.
• beneficiary.additional_info.personal_email (Optional): Specify this parameter if you want the beneficiary to receive an email notification upon payout being dispatched. Please contact your Account Manager to enable this feature beforehand.

Bank account beneficiary

Example request

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/beneficiaries/create' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '{
6    "beneficiary": {
7      "additional_info": {
8        "personal_email": "[email protected]"
9      },
10      "address": {
11        "city": "Seattle",
12        "country_code": "US",
13        "postcode": "98104",
14        "state": "Washington",
15        "street_address": "412 5th Avenue"
16      },
17      "bank_details": {
18        "account_currency": "USD",
19        "account_name": "John Walker",
20        "account_number": "50001121",
21        "account_routing_type1": "aba",
22        "account_routing_value1": "021000021",
23        "bank_country_code": "US",
24        "local_clearing_system": "ACH"
25      },
26      "entity_type": "COMPANY"
27    },
28    "transfer_methods": [
29        "LOCAL"
30    ]
31}'

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.

Example response

JSON
1{
2    "beneficiary": {
3        "additional_info": {
4            "personal_email": "[email protected]"
5        },
6        "address": {
7            "city": "Seattle",
8            "country_code": "US",
9            "postcode": "98104",
10            "state": "Washington",
11            "street_address": "412 5th Avenue"
12        },
13        "bank_details": {
14            "account_currency": "USD",
15            "account_name": "John Walker",
16            "account_number": "50001121",
17            "account_routing_type1": "aba",
18            "account_routing_value1": "021000021",
19            "bank_country_code": "US",
20            "bank_name": "JPMorgan Chase Bank, NA",
21            "local_clearing_system": "ACH"
22        },
23        "entity_type": "COMPANY",
24        "type": "BANK_ACCOUNT"
25    },
26    "id": "370d83d6-52e8-4bdd-97b6-56d18c5ba4d0",
27    "payer_entity_type": "COMPANY",
28    "transfer_methods": [
29        "LOCAL"
30    ]
31}

Digital wallet beneficiary

Example request

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/beneficiaries/create' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '{
6   "beneficiary": { 
7    "digital_wallet":{
8        "id_type":"account_number",
9        "id_value":"1033106816639334",
10        "provider":"AIRWALLEX",
11        "account_name":"John Walker Corporation"
12    },
13    "type": "DIGITAL_WALLET"
14  }, 
15  "transfer_methods": [
16        "LOCAL"
17    ]
18}'

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.

Example response

JSON
1{
2    "beneficiary": {
3        "digital_wallet": {
4            "account_name": "John Walker Corporation",
5            "id_type": "account_number",
6            "id_value": "1033106816639334",
7            "provider": "AIRWALLEX"
8        },
9        "type": "DIGITAL_WALLET"
10    },
11    "id": "c7d0d874-477e-46ef-ba36-56613227e092",
12    "payer_entity_type": "COMPANY",
13    "transfer_methods": [
14        "LOCAL"
15    ]
16}