Skip to main content
GET
Get Recipient by Merchant ID
Use GET /v1/recipients?merchant_recipient_id=... to look up a recipient by your merchant recipient ID. The lookup is scoped to your organization and does not require account_id. A successful request returns a top-level recipient object. If no recipient matches, the endpoint returns HTTP 400 with code RECIPIENT_NOT_FOUND. The merchant_recipient_id query parameter is required. This endpoint keeps its existing behavior. Existing integrations that use it to look up a recipient do not need to change. For a paginated collection, use List Recipients at GET /v1/recipients/list. That endpoint returns a data array and pagination, including an empty array when no recipients match. Integrations or cron jobs that need a list should use /list. To look up a recipient by its Yuno ID, use Get Recipient.

Authorizations

public-api-key
string
header
default:<Your public-api-key>
required
private-secret-key
string
header
default:<Your private-secret-key>
required

Query Parameters

merchant_recipient_id
string
required

The recipient identifier assigned by the merchant.

Minimum string length: 1

Response

Success Response

id
string

The unique identifier of the recipient.

Example:

"3aaa4d82-11e8-48ce-8ef5-04eee3a10802"

account_id
string

The account identifier associated with this recipient.

Example:

"fe14c7c6-c75e-43b7-bdbe-4c87ad52c482"

merchant_recipient_id
string

Unique identifier of the recipient defined by the merchant.

Example:

"MERCHANT_182acf1d-faeb-4ff0-94cd-7fab11b282f6"

national_entity
string

Beneficiary's national entity type.

Example:

"INDIVIDUAL"

entity_type
string

Beneficiary's type of organization.

Example:

"PRIVATE"

first_name
string

Beneficiary's name.

Example:

"Juan"

last_name
string

Beneficiary's last name.

Example:

"Perez"

Beneficiary's legal name.

Example:

null

email
string

The Beneficiary's email.

Example:

"juan.perez@example.com"

date_of_birth
string

Beneficiary's date of birth.

Example:

"1990-01-15"

country
string

The Beneficiary's country.

Example:

"CO"

website
string

The seller's website URL.

Example:

"https://juanperez.com"

industry
string

The seller's industry.

Example:

"Technology"

merchant_category_code
string

The merchant category code (MCC) (MAX 235; MIN 1).

Example:

"5734"

document
object
phone
object
address
object
withdrawal_methods
object
documentation
object[]
onboardings
object[]
split_configuration
object

Rules for automatic split calculation at the recipient level.

created_at
string<date-time>

Recipient creation date (ISO 8601 MAX 27; MIN 27).

Example:

"2025-08-27T15:41:19.497413Z"

updated_at
string<date-time>

Last Recipient updated date (ISO 8601 MAX 27; MIN 27).

Example:

"2025-08-27T15:41:19.497425Z"