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.

ActionEndpoint
Create a recipientPOST /api/v1/applications/recipients
Retrieve a recipientGET /api/v1/applications/recipients/{recipient_uuid}
List all recipientsGET /api/v1/applications/recipients
Update a recipientPUT /api/v1/applications/recipients/{recipient_uuid}
Delete a recipientDELETE /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: name and payload.
  • name must be unique within your application.
  • payload holds the saved fields. It uses the same field names as the transfer requirements, written as one flat path, such as destination.beneficiary_info.beneficiary_name or destination.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 a payload, 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, leave payload out.

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.


Did this page help you?