Add a beneficiary
Adds a beneficiary under the association resolved from the token.
Required-field enforcement is handled by the upstream service, not the
gateway. Payment destinations are managed separately via the
/payment-destinations sub-resource.
curl --request POST \
--url https://api.zeam.money/gw/v1/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-zeam-auth: <api-key>' \
--data '
{
"beneficiaryType": "Business",
"reference": "ACME-001",
"business": {
"companyName": "Acme Ltd",
"registrationNumber": "2020/123456/07",
"countryOfRegistration": "ZA"
}
}
'{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"individual": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"firstName": "<string>",
"lastName": "<string>",
"idNumber": "<string>",
"dateOfBirth": "2023-12-25",
"nationality": "<string>",
"mobileNumber": "<string>",
"email": "jsmith@example.com",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"business": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"companyName": "<string>",
"registrationNumber": "<string>",
"countryOfRegistration": "<string>",
"taxId": "<string>",
"industry": "<string>",
"contactPersonName": "<string>",
"contactNumber": "<string>",
"contactEmail": "jsmith@example.com",
"registeredAddress": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"paymentDestinations": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"method": "BANK",
"beneficiaryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "<string>",
"isPrimary": true,
"countryIsoCode2": "<string>",
"currencyIsoCode3": "<string>",
"bankName": "<string>",
"bankCode": "<string>",
"accountNumber": "<string>",
"accountName": "<string>",
"accountType": "<string>",
"sortCode": "<string>",
"iban": "<string>",
"swiftBic": "<string>",
"branchCode": "<string>",
"mobileNumber": "<string>",
"mobileProvider": "<string>",
"networkName": "<string>",
"assetSymbol": "<string>",
"walletAddress": "<string>",
"isZeamAccount": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"addresses": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"addressType": "<string>",
"addressLine1": "<string>",
"addressLine2": "<string>",
"city": "<string>",
"stateProvince": "<string>",
"postalCode": "<string>",
"countryCode": "<string>",
"isPrimary": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"tags": [
{
"tag": "<string>",
"createdAt": "2023-11-07T05:31:56Z"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}Authorizations
Access token issued by POST /v1/auth/token.
Application secret (the apiKey issued at registration), validated at the Kong edge.
Body
Used for both POST (create) and PATCH (update) beneficiary requests.
For PATCH, only fields present in the body are changed. beneficiaryType
is always required — echo it from a prior Get even when not changing it.
Payment destinations are managed separately via the
/payment-destinations sub-resource.
Response
Beneficiary created.
Individual, Business Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
curl --request POST \
--url https://api.zeam.money/gw/v1/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-zeam-auth: <api-key>' \
--data '
{
"beneficiaryType": "Business",
"reference": "ACME-001",
"business": {
"companyName": "Acme Ltd",
"registrationNumber": "2020/123456/07",
"countryOfRegistration": "ZA"
}
}
'{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"individual": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"firstName": "<string>",
"lastName": "<string>",
"idNumber": "<string>",
"dateOfBirth": "2023-12-25",
"nationality": "<string>",
"mobileNumber": "<string>",
"email": "jsmith@example.com",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"business": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"companyName": "<string>",
"registrationNumber": "<string>",
"countryOfRegistration": "<string>",
"taxId": "<string>",
"industry": "<string>",
"contactPersonName": "<string>",
"contactNumber": "<string>",
"contactEmail": "jsmith@example.com",
"registeredAddress": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"paymentDestinations": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"method": "BANK",
"beneficiaryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "<string>",
"isPrimary": true,
"countryIsoCode2": "<string>",
"currencyIsoCode3": "<string>",
"bankName": "<string>",
"bankCode": "<string>",
"accountNumber": "<string>",
"accountName": "<string>",
"accountType": "<string>",
"sortCode": "<string>",
"iban": "<string>",
"swiftBic": "<string>",
"branchCode": "<string>",
"mobileNumber": "<string>",
"mobileProvider": "<string>",
"networkName": "<string>",
"assetSymbol": "<string>",
"walletAddress": "<string>",
"isZeamAccount": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"addresses": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"addressType": "<string>",
"addressLine1": "<string>",
"addressLine2": "<string>",
"city": "<string>",
"stateProvince": "<string>",
"postalCode": "<string>",
"countryCode": "<string>",
"isPrimary": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"tags": [
{
"tag": "<string>",
"createdAt": "2023-11-07T05:31:56Z"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}