Create Recipient

POST /recipients

cURL

Individual Recipient

curl --request POST \ --url https://api-sandbox.y.uno/v1/recipients \ --header 'Content-Type: application/json' \ --header 'private-secret-key: <api-key>' \ --header 'public-api-key: <api-key>' \ --data ' { "account_id": "9104911d-5df9-429e-8488-ad41abea1a4b", "merchant_recipient_id": "AAAA01", "national_entity": "INDIVIDUAL", "first_name": "John", "last_name": "Doe", "email": "[e-mail]", "country": "CO", "document": { "document_number": "1093333333", "document_type": "CC" }, "phone": { "country_code": "57", "number": "3132450765" }, "address": { "address_line_1": "Calle 34 # 56 - 78", "address_line_2": "Apartamento 502, Torre I", "city": "Bogota", "country": "CO", "state": "Cundinamarca", "zip_code": "111111" }, "withdrawal_methods": { "bank": { "code": "246", "branch": "XXXX", "account": "1093333333", "account_type": "SAVINGS" } }, "onboardings": [ { "type": "PREVIOUSLY_ONBOARDED", "workflow": "DIRECT", "description": "Onboarding Description", "callback_url": "https://merchant.example.com/webhook/onboarding", "provider": { "id": "VR", "connection_id": "d2c1f0e9-8a90-432a-ab7c-fdee4c7d58e4", "recipient_id": "adct_1SB05NPD2RTdZORd", "recipient_type": "FLEET" }, "documentation": [ { "file_name": "onboarding12.png", "content_type": "image/png", "content_category": "VAT_DOCUMENT", "content": "VGV4dG8gZGUgZWplbXBsbyBwYXJhIEJhc2U2NA==" } ], "terms_of_service": { "acceptance": true, "date": "2025-07-21T20:43:54.786342Z", "ip": "129.21.111.11" } } ], "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } '

201

Success Response

{ "id": "3aaa4d82-11e8-48ce-8ef5-04eee3a10802", "account_id": "fe14c7c6-c75e-43b7-bdbe-4c87ad52c482", "merchant_recipient_id": "MERCHANT_182acf1d-faeb-4ff0-94cd-7fab11b282f6", "national_entity": "INDIVIDUAL", "entity_type": "PRIVATE", "first_name": "Juan", "last_name": "Pérez", "legal_name": null, "email": "[e-mail]", "date_of_birth": "1990-01-15", "country": "CO", "website": "https://juanperez.com", "industry": "Technology", "merchant_category_code": "5734", "document": { "document_number": "1234567890", "document_type": "CC" }, "phone": { "country_code": "57", "number": "3001234567" }, "address": { "address_line_1": "Carrera 7 # 32-16", "address_line_2": "Oficina 201", "city": "Bogotá", "country": "CO", "state": "Cundinamarca", "zip_code": "110311", "neighborhood": "Centro" }, "legal_representatives": [ { "merchant_reference": "REP_001", "first_name": "María", "last_name": "González", "email": "[e-mail]", "date_of_birth": "1985-05-20", "country": "CO", "nationality": "CO", "title": "CEO", "publicly_exposed_person": false, "ultimate_beneficial_owner": true, "document": { "document_type": "CC", "document_number": "0987654321" }, "phone": { "country_code": "57", "number": "3109876543" }, "address": { "address_line_1": "Calle 26 # 13-19", "address_line_2": null, "country": "CO", "state": "Cundinamarca", "city": "Bogotá", "zip_code": "110311" } } ], "withdrawal_methods": { "bank": { "code": "001", "branch": "004", "branch_digit": "123", "account": "1234567890", "account_digit": "123", "account_type": "SAVINGS", "routing": "021000021", "country": "CO", "currency": "COP" } }, "documentation": [ { "file_name": "cc-front.pdf", "content_type": "application/pdf", "content_category": "IDENTIFICATION", "content": "JVBERi0xLjQKJ..." } ], "onboardings": [ { "id": "84c42684-dbe5-4e0f-bd17-4d094e19762d", "type": "TWO_STEP_ONBOARDING", "workflow": "DIRECT", "status": "PENDING", "callback_url": "https://merchant.example.com/webhook/onboarding", "provider": { "id": "ALELO", "connection_id": "cc389b51-53a1-4a29-af40-c8cee26c3399", "recipient_id": null, "redirect_url": null, "onboarding_url": null, "legal_entity": null, "balance_account_id": null, "legal_entity_id": null }, "documentation": [ { "file_name": "utility-bill.pdf", "content_type": "application/pdf", "content_category": "ADDRESS_PROOF", "content": "JVBERi0xLjQKJ..." } ], "requirements": [ { "field": "document.cc", "message": "Provide CC document image", "status": "PENDING" }, { "field": "address.proof", "message": "Upload proof of address", "status": "PENDING" } ], "withdrawal_methods": { "bank": { "code": "002", "branch": "002", "branch_digit": null, "account": "9876543210", "account_digit": null, "account_type": "SAVINGS", "routing": "021000022", "country": "CO", "currency": "COP" } }, "terms_of_service": { "acceptance": true, "date": "2025-07-21T20:43:54Z", "ip": "129.21.111.11" }, "created_at": "2025-08-27T15:41:19.516982Z", "updated_at": "2025-08-27T15:41:19.516989Z" } ], "created_at": "2025-08-27T15:41:19.497413Z", "updated_at": "2025-08-27T15:41:19.497425Z" }

Creates a new recipient for split payment scenarios. This endpoint allows merchants to define recipients that can receive portions of payments in marketplace or split payment models.

Authorizations

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

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

Body

application/json

account_id · string · required

Unique id of the account in Yuno (MAX 64; MIN 36).

Example:

"9104911d-5df9-429e-8488-ad41abea1a4b"

merchant_recipient_id · string · required

Unique identifier of the recipient defined by the merchant (MAX 255; MIN 1).

Example:

"AAAA01"

national_entity · enum<string> · required

Beneficiary's national entity type. Could be INDIVIDUAL or ENTITY.

Available options: INDIVIDUAL, ENTITY

Example:

"INDIVIDUAL"

first_name · string · required

Beneficiary's name. (MAX 80; MIN 1).

Example:

"John"

last_name · string · required

Beneficiary's last name. (MAX 80; MIN 1).

Example:

"Doe"

country · string · required

The Beneficiary's country (ISO 3166-1 MAX 2; MIN 2).

Example:

"CO"

entity_type · enum<string>

The Beneficiary's type of organization. GOVERNMENTAL, PUBLIC, NON_PROFIT, PRIVATE

Available options: GOVERNMENTAL, PUBLIC, NON_PROFIT, PRIVATE

Example:

"PRIVATE"

date_of_birth · string

The Beneficiary's date of birth in the YYYY-MM-DD format (MAX 10; MIN 10).

Required string length: 10

Example:

"1990-02-28"

legal_name · string

Beneficiary's name. (MAX 80; MIN 1) Only necessary when national entity is ENTITY.

Example:

"Arcos dorados S.A."

email · string

The Beneficiary's email (MAX 255; MIN 3).

Example:

"[e-mail]"

website · string

The seller's website URL (MAX 255; MIN 3).

Required string length: 3 - 255

Example:

"https://y.uno"

industry · string

The seller's industry (MAX 235; MIN 1). For more information access the Industry category reference page.

Required string length: 1 - 235

Example:

"VIRTUAL_GOODS"

merchant_category_code · string

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

document · object

Beneficiary's document information

Show child attributes

phone · object

Specifies the customer's phone number object.

Show child attributes

address · object

Address

Show child attributes

split_configuration · object

Rules for automatic split calculation at the recipient level.

Show child attributes

legal_representatives · object[]

Owners/beneficials of the recipient. Required when national_entity = ENTITY.

Show child attributes

withdrawal_methods · object

Withdrawal methods for the merchant

Show child attributes

documentation · object[]

Array of documentation objects

Show child attributes

onboardings · object[]

Array of onboarding objects for different payment providers

Show child attributes

Response

201

application/json

Recipient created successfully

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"

legal_name · string | null

Beneficiary's legal name.

Example:

null

email · string

The Beneficiary's email.

Example:

"[e-mail]"

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

Show child attributes

phone · object

Show child attributes

address · object

Show child attributes

legal_representatives · object[]

Show child attributes

withdrawal_methods · object

Show child attributes

documentation · object[]

Show child attributes

onboardings · object[]

Show child attributes

split_configuration · object

Rules for automatic split calculation at the recipient level.

Show child attributes

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"