Recipients
Save a beneficiary's payout details once, and reuse them in transfers.
A Recipient is a saved beneficiary: the person or business that receives a transfer, with their payout details. Reference it when you create a transfer, and Harbor fills in the destination fields for you. The docs and the Portal use recipient and beneficiary interchangeably.
| Action | Endpoint |
|---|---|
| Create a recipient | POST /api/v1/applications/recipients |
| Retrieve a recipient | GET /api/v1/applications/recipients/{recipient_uuid} |
| List all recipients | GET /api/v1/applications/recipients |
| Update a recipient | PUT /api/v1/applications/recipients/{recipient_uuid} |
| Delete a recipient | DELETE /api/v1/applications/recipients/{recipient_uuid} |
Recipients can also be managed in the Harbor Portal. See Recipients in the Portal.
Create a Recipient
POST /api/v1/applications/recipients
- Required:
nameandpayload. namemust be unique within your application.payloadholds the saved fields. It uses the same field names as the transfer requirements, written as one flat path, such asdestination.beneficiary_info.beneficiary_nameordestination.payout_instrument.address.- Harbor doesn't check the field names when you save a recipient. A misspelled field is saved without an error, and isn't used when the transfer is created.
- A recipient is for one route. See One Recipient per Route.
curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/applications/recipients' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
"name": "{{RECIPIENT_NAME}}",
"payload": {
"destination.beneficiary_info.beneficiary_name": "{{BENEFICIARY_NAME}}",
"destination.beneficiary_info.beneficiary_address.street": "{{STREET}}",
"destination.beneficiary_info.beneficiary_address.city": "{{CITY}}",
"destination.beneficiary_info.beneficiary_address.state_province": "{{STATE}}",
"destination.beneficiary_info.beneficiary_address.postal_code": "{{POSTAL_CODE}}",
"destination.beneficiary_info.beneficiary_address.country": "{{COUNTRY}}",
"destination.payout_instrument.address": "{{WALLET_ADDRESS}}",
"destination.transfer_purpose": "{{TRANSFER_PURPOSE}}",
"destination.is_self_transfer": false
}
}'{
"data": {
"object": "recipient",
"uuid": "rcpt_YTnUYXmT5UsO9IiKXftKS1hsxOdQ4Q7ow5qvvSTN",
"name": "Docs Sample Wallet Recipient",
"payload": {
"destination.is_self_transfer": false,
"destination.transfer_purpose": "TRANSFER_TO_OWN_ACCOUNT",
"destination.payout_instrument.address": "0x76da4165da3d87b0dfcfeb867a31a0d7ab9884a5",
"destination.beneficiary_info.beneficiary_name": "Sample Beneficiary",
"destination.beneficiary_info.beneficiary_address.city": "Austin",
"destination.beneficiary_info.beneficiary_address.street": "123 Main St",
"destination.beneficiary_info.beneficiary_address.country": "US",
"destination.beneficiary_info.beneficiary_address.postal_code": "78701",
"destination.beneficiary_info.beneficiary_address.state_province": "TX"
},
"created_at": "2026-10-06T01:28:23+00:00",
"updated_at": "2026-10-06T01:58:58+00:00"
}
}Save the uuid. You use it to reference the recipient in transfers.
Retrieve a Recipient
GET /api/v1/applications/recipients/{recipient_uuid}
Returns one recipient. The response has the same fields as Create a Recipient, plus customer_uuid.
curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/applications/recipients/{{RECIPIENT_UUID}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'{
"data": {
"object": "recipient",
"uuid": "rcpt_YTnUYXmT5UsO9IiKXftKS1hsxOdQ4Q7ow5qvvSTN",
"customer_uuid": null,
"name": "Docs Sample Wallet Recipient",
"payload": {
"destination.is_self_transfer": false,
"destination.transfer_purpose": "TRANSFER_TO_OWN_ACCOUNT",
"destination.payout_instrument.address": "0x76da4165da3d87b0dfcfeb867a31a0d7ab9884a5",
"destination.beneficiary_info.beneficiary_name": "Sample Beneficiary",
"destination.beneficiary_info.beneficiary_address.city": "Austin",
"destination.beneficiary_info.beneficiary_address.street": "123 Main St",
"destination.beneficiary_info.beneficiary_address.country": "US",
"destination.beneficiary_info.beneficiary_address.postal_code": "78701",
"destination.beneficiary_info.beneficiary_address.state_province": "TX"
},
"created_at": "2026-10-06T01:28:23+00:00",
"updated_at": "2026-10-06T01:58:58+00:00"
}
}List All Recipients
GET /api/v1/applications/recipients
Returns your recipients, 15 per page.
curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/applications/recipients?page={{PAGE}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'{
"data": [
{
"object": "recipient",
"uuid": "rcpt_YTnUYXmT5UsO9IiKXftKS1hsxOdQ4Q7ow5qvvSTN",
"name": "Docs Sample Wallet Recipient",
"payload": { ... },
"created_at": "2026-10-06T01:28:23+00:00",
"updated_at": "2026-10-06T01:58:58+00:00"
}
],
"links": {
"first": "https://harbor-sandbox.owlpay.com/api/v1/applications/recipients?page=1",
"last": "https://harbor-sandbox.owlpay.com/api/v1/applications/recipients?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://harbor-sandbox.owlpay.com/api/v1/applications/recipients",
"per_page": 15,
"to": 1,
"total": 1
}
}To get the next page, call links.next. It is null on the last page.
Update a Recipient
PUT /api/v1/applications/recipients/{recipient_uuid}
Updates a recipient's name, payload, or both.
curl --location --request PUT 'https://harbor-sandbox.owlpay.com/api/v1/applications/recipients/{{RECIPIENT_UUID}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
"name": "{{RECIPIENT_NAME}}",
"payload": {
"destination.beneficiary_info.beneficiary_name": "{{BENEFICIARY_NAME}}",
"destination.payout_instrument.address": "{{WALLET_ADDRESS}}",
"destination.transfer_purpose": "{{TRANSFER_PURPOSE}}",
"destination.is_self_transfer": false
}
}'The response returns the updated recipient.
The payload is replaced, not merged
If you send apayload, it replaces the saved payload. Fields you leave out are deleted. To change one field, send the full payload with that field changed. To change only the name, leavepayloadout.
Delete a Recipient
DELETE /api/v1/applications/recipients/{recipient_uuid}
curl --location --request DELETE 'https://harbor-sandbox.owlpay.com/api/v1/applications/recipients/{{RECIPIENT_UUID}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'{
"message": "The application recipient was deleted successfully.",
"data": null
}Use a Recipient in a Transfer
When you create a transfer, add recipient_id with the recipient's uuid. You can also use recipient_name with its name.
Harbor fills in the destination fields from the saved recipient. Any field you send in destination overrides the saved value for this transfer only.
curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
"quote_id": "{{QUOTE_ID}}",
"on_behalf_of": "{{CUSTOMER_UUID}}",
"application_transfer_uuid": "{{APPLICATION_TRANSFER_UUID}}",
"recipient_id": "{{RECIPIENT_UUID}}",
"destination": {
"transfer_purpose": "SALARY",
"beneficiary_receiving_wallet_type": "non_custodial",
"beneficiary_institution_name": "Self-hosted wallet"
}
}'In this example, the beneficiary's name, address and wallet address come from the recipient. transfer_purpose is overridden to SALARY, and the wallet type and institution are added for this transfer.
- The recipient must contain every required field, or you must send the missing ones in
destination. Otherwise, the transfer is rejected. - The recipient can't contain fields from another route. See One Recipient per Route.
- If the recipient doesn't exist or belongs to another application, the transfer is rejected with error
2005.
For when to set is_self_transfer, see Third-Party Recipients.
One Recipient per Route
A recipient is for one route: one country and one payment method, with the payout details for it. The fields each route needs are different, so details aren't shared between routes, even for the same person.
To send to the same person in a different way, create a separate recipient for each route. For example, to pay Sam Rivera to their bank account in Mexico and to their wallet:
{
"name": "Sam Rivera - SPEI",
"payload": {
"destination.beneficiary_info.beneficiary_name": "Sam Rivera",
"destination.beneficiary_info.beneficiary_address.street": "Av. Paseo de la Reforma 222",
"destination.beneficiary_info.beneficiary_address.city": "Ciudad de Mexico",
"destination.beneficiary_info.beneficiary_address.state_province": "CMX",
"destination.beneficiary_info.beneficiary_address.postal_code": "06600",
"destination.beneficiary_info.beneficiary_address.country": "MX",
"destination.beneficiary_info.beneficiary_id_doc_number": "RISA900101HDFVMM09",
"destination.beneficiary_info.beneficiary_dob": "1990-01-01",
"destination.payout_instrument.mx_clabe": "032180000118359719",
"destination.transfer_purpose": "FAMILY_MAINTENANCE",
"destination.is_self_transfer": false
}
}{
"name": "Sam Rivera - Wallet",
"payload": {
"destination.beneficiary_info.beneficiary_name": "Sam Rivera",
"destination.beneficiary_info.beneficiary_address.street": "Av. Paseo de la Reforma 222",
"destination.beneficiary_info.beneficiary_address.city": "Ciudad de Mexico",
"destination.beneficiary_info.beneficiary_address.state_province": "CMX",
"destination.beneficiary_info.beneficiary_address.postal_code": "06600",
"destination.beneficiary_info.beneficiary_address.country": "MX",
"destination.payout_instrument.address": "0x76da4165da3d87b0dfcfeb867a31a0d7ab9884a5",
"destination.transfer_purpose": "FAMILY_MAINTENANCE",
"destination.is_self_transfer": false,
"destination.beneficiary_receiving_wallet_type": "non_custodial",
"destination.beneficiary_institution_name": "Self-hosted wallet"
}
}Each recipient has every field its route requires. The name and address are the same in both, and the rest is specific to the route.
Using a Recipient on the Wrong Route
If you use "Sam Rivera - SPEI" for a transfer to a wallet, the transfer is rejected with 422. The wallet fields are missing, and mx_clabe isn't allowed on that route:
{
"message": "The required properties (beneficiary_receiving_wallet_type, beneficiary_institution_name) are missing (and 1 more error)",
"error": "The required properties (beneficiary_receiving_wallet_type, beneficiary_institution_name) are missing (and 1 more error)",
"code": 2005,
"error_type": "general.validation_error",
"errors": {
"/destination": [
"The required properties (beneficiary_receiving_wallet_type, beneficiary_institution_name) are missing"
],
"/destination/payout_instrument": [
"Additional object properties are not allowed: mx_clabe"
]
}
}Sending the missing fields in destination doesn't fix it, because the saved mx_clabe is still sent. Use "Sam Rivera - Wallet" instead.
Updated about 1 month ago