Create beneficiaries

Copy for LLMView as Markdown

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

Refer to the dynamic schemaAPI 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, a DIGITAL_WALLET (including Airwallex Pay), or a STABLECOIN_WALLET. 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 schemaAPI or call Get the API schemaAPI 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 schemaAPI or call Get the API schemaAPI to obtain the corresponding parameter requirements.
beneficiary.stablecoin_wallet: Required beneficiary stablecoin wallet parameters (asset, network, address) will vary according to the specified stablecoin and network. See Stablecoin wallet payout network for supported coverage.
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 schemaAPI or call Get the API schemaAPI 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 -X POST https://api.sandbox.airwallex.com/api/v1/beneficiaries/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "beneficiary": {
6      "additional_info": {
7        "personal_email": "[email protected]"
8      },
9      "address": {
10        "city": "Seattle",
11        "country_code": "US",
12        "postcode": "98104",
13        "state": "Washington",
14        "street_address": "412 5th Avenue"
15      },
16      "bank_details": {
17        "account_currency": "USD",
18        "account_name": "John Walker",
19        "account_number": "50001121",
20        "account_routing_type1": "aba",
21        "account_routing_value1": "021000021",
22        "bank_country_code": "US",
23        "local_clearing_system": "ACH"
24      },
25      "entity_type": "COMPANY"
26    },
27    "transfer_methods": [
28      "LOCAL"
29    ]
30  }'

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 -X POST https://api.sandbox.airwallex.com/api/v1/beneficiaries/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "beneficiary": {
6      "digital_wallet": {
7        "id_type": "account_number",
8        "id_value": "1033106816639334",
9        "provider": "AIRWALLEX",
10        "account_name": "John Walker Corporation"
11      },
12      "type": "DIGITAL_WALLET"
13    },
14    "transfer_methods": [
15      "LOCAL"
16    ]
17  }'

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}

Stablecoin wallet beneficiary

Specify the beneficiary type as STABLECOIN_WALLET and provide a stablecoin_wallet object with the asset, network, and address. See Stablecoin wallet payout network for supported coverage.

Sending stablecoins to an incorrect wallet address or unsupported network will result in the irreversible loss of funds. Always verify the recipient wallet address and network before initiating a transfer.

Example request

Shell

1curl -X POST https://api.sandbox.airwallex.com/api/v1/beneficiaries/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "beneficiary": {
6      "additional_info": {
7        "business_registration_number": "123456789"
8      },
9      "address": {
10        "country_code": "US"
11      },
12      "entity_type": "COMPANY",
13      "company_name": "Acme Web3 Ltd",
14      "stablecoin_wallet": {
15        "asset": "USDC",
16        "network": "ETHEREUM",
17        "address": "0x5abfe17b2e9e1234567890abcdef1234567890"
18      },
19      "type": "STABLECOIN_WALLET"
20    },
21    "nickname": "Acme-USDC-Rail"
22  }'

Example response

JSON

1{
2    "beneficiary": {
3        "additional_info": {
4            "business_registration_number": "123456789"
5        },
6        "address": {
7            "country_code": "US"
8        },
9        "company_name": "Acme Web3 Ltd",
10        "entity_type": "COMPANY",
11        "stablecoin_wallet": {
12            "asset": "USDC",
13            "network": "ETHEREUM",
14            "address": "0x5abfe17b2e9e1234567890abcdef1234567890"
15        },
16        "type": "STABLECOIN_WALLET"
17    },
18    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
19    "nickname": "Acme-USDC-Rail",
20    "payer_entity_type": "COMPANY"
21}

Was this page helpful?