curl --request POST \
--url https://sandbox-api.va.meridianpay.com/v1/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"type": "BUSINESS",
"name": "Nimbus Settlement Ltd",
"displayName": "Nimbus Settlement Ltd",
"email": "treasury@nimbus-settlement.com",
"relationshipToUser": "THIRD_PARTY",
"address": {
"addressLine1": "25 Sir John Rogerson's Quay",
"city": "Dublin",
"stateProvince": "County Dublin",
"postalCode": "D02 XY45",
"countryCode": "IE"
},
"instrument": {
"type": "BLOCKCHAIN_WALLET",
"displayName": "Nimbus settlement wallet",
"walletAddress": "0x9f8B4a71Cc0Ed2b3F6a9E7c1D5b8A2f4E6c04C21",
"currency": "USDC_ETH",
"idempotencyKey": "a1b2c3d4-1111-2222-3333-444455556666"
}
}
EOF{
"id": "uspay-z2oaq71hlo7fhvck2xw0nidg",
"counterpartyId": "uspay-z2oaq71hlo7fhvck2xw0nidg",
"createdAt": "2026-09-09T20:39:30Z",
"updatedAt": "2026-09-09T20:39:30Z",
"name": "Nimbus Settlement Ltd",
"displayName": "Nimbus Settlement Ltd",
"email": "treasury@nimbus-settlement.com",
"address": {
"addressLine1": "25 Sir John Rogerson's Quay",
"city": "Dublin",
"stateProvince": "County Dublin",
"postalCode": "D02 XY45",
"countryCode": "IE"
},
"relationshipToUser": "THIRD_PARTY",
"type": "BUSINESS"
}Create a Beneficiary
Creates a beneficiary together with its first payout instrument for the authenticated Meridian account. The instrument is either a bank account (BANK_ACCOUNT) or a stablecoin wallet address (BLOCKCHAIN_WALLET); further instruments are attached with POST /v1/beneficiaries/{beneficiaryId}/instruments.
curl --request POST \
--url https://sandbox-api.va.meridianpay.com/v1/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"type": "BUSINESS",
"name": "Nimbus Settlement Ltd",
"displayName": "Nimbus Settlement Ltd",
"email": "treasury@nimbus-settlement.com",
"relationshipToUser": "THIRD_PARTY",
"address": {
"addressLine1": "25 Sir John Rogerson's Quay",
"city": "Dublin",
"stateProvince": "County Dublin",
"postalCode": "D02 XY45",
"countryCode": "IE"
},
"instrument": {
"type": "BLOCKCHAIN_WALLET",
"displayName": "Nimbus settlement wallet",
"walletAddress": "0x9f8B4a71Cc0Ed2b3F6a9E7c1D5b8A2f4E6c04C21",
"currency": "USDC_ETH",
"idempotencyKey": "a1b2c3d4-1111-2222-3333-444455556666"
}
}
EOF{
"id": "uspay-z2oaq71hlo7fhvck2xw0nidg",
"counterpartyId": "uspay-z2oaq71hlo7fhvck2xw0nidg",
"createdAt": "2026-09-09T20:39:30Z",
"updatedAt": "2026-09-09T20:39:30Z",
"name": "Nimbus Settlement Ltd",
"displayName": "Nimbus Settlement Ltd",
"email": "treasury@nimbus-settlement.com",
"address": {
"addressLine1": "25 Sir John Rogerson's Quay",
"city": "Dublin",
"stateProvince": "County Dublin",
"postalCode": "D02 XY45",
"countryCode": "IE"
},
"relationshipToUser": "THIRD_PARTY",
"type": "BUSINESS"
}Authorizations
Bearer token authentication, for client-server calls.
Send the access token issued by POST /v1/auth/token as Authorization: Bearer {token}. The token carries its own program and user context, so the X-Meridian-* headers are not required. See Authentication.
Headers
Server-to-server (HMAC) requests only. Partner API key issued by Meridian during provisioning.
Server-to-server (HMAC) requests only. Current time in milliseconds since the Unix epoch. Must be within 60 seconds of the request.
Server-to-server (HMAC) requests only. Identifies the program context for the request.
Server-to-server (HMAC) requests only. Identifies the Meridian user targeted by the request. Required for MULTI_USER integrations; omit for SINGLE_USER.
Body
Beneficiary identity and first payout instrument
- Create Person Beneficiary Request
- Create Business Beneficiary Request
Create a person beneficiary together with its first instrument
First name
"Sherlock"
Last name
"Holmes"
Address of the beneficiary's bank. Required by RouteFusion for non-US bank countries; a missing field is reported as a field-level validation error on submission.
Show child attributes
Show child attributes
Bank account instrument to create for a beneficiary
- Bank Account Instrument Request
- Wallet Instrument Request
Show child attributes
Show child attributes
Beneficiary type discriminator
PERSON, BUSINESS Date of birth
"1854-01-06"
Human-readable display name for the beneficiary
"Sherlock Holmes"
Email address
Phone number
ISO 3166-1 alpha-2 country code of the phone number
"GB"
Beneficiary's relationship to the account owner
SELF, THIRD_PARTY, null "THIRD_PARTY"
Response
The newly created beneficiary
- Person Beneficiary Response
- Business Beneficiary Response
A person beneficiary
Unique identifier of the beneficiary
"uscp-01JMERBENEF001"
Identifier of the underlying counterparty
"uscp-01JMERBENEF001"
Timestamp when the beneficiary was created
"2026-04-30T14:00:00Z"
Timestamp when the beneficiary was last updated
"2026-04-30T14:00:00Z"
Beneficiary type discriminator
PERSON, BUSINESS First name of the beneficiary
Last name of the beneficiary
Date of birth of the beneficiary
Display name of the beneficiary
Email address of the beneficiary
Phone number of the beneficiary
Address of the beneficiary's bank. Required by RouteFusion for non-US bank countries; a missing field is reported as a field-level validation error on submission.
Show child attributes
Show child attributes
Beneficiary's relationship to the account owner
SELF, THIRD_PARTY, null "THIRD_PARTY"