Update Recipient

PATCH

recipients

{recipient_id}

curl --request PATCH \
  --url https://api-sandbox.y.uno/v1/recipients/{recipient_id} \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "email": "newemail@example.com",
  "phone": {
    "country_code": "57",
    "number": "9876543210"
  }
}
'

{
  "id": "9104911d-5df9-429e-8488-ad41abea1a4b",
  "account_id": "9104911d-5df9-429e-8488-ad41abea1a4b",
  "merchant_recipient_id": "AAAA01",
  "national_entity": "INDIVIDUAL",
  "first_name": "John",
  "last_name": "Doe",
  "email": "newemail@example.com",
  "country": "CO",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:45:00Z"
}

Updates an existing recipient. Only specified fields will be updated.

Bank-account updates

For Zoop and Pagar.me onboardings with a provider recipient ID, an explicit withdrawal_methods.bank update waits for the provider result. Other recipient fields retain their existing update behavior. Without onboarding_id, Yuno combines the bank fields you send with the recipient’s saved bank account to form one account for eligible onboardings. It does not combine your request with each provider’s different bank account. Send a complete account if the saved account does not provide the missing fields. Accepted account types are CHECKINGS and SAVINGS. With onboarding_id, the bank update targets only that onboarding and leaves the recipient default and other onboardings unchanged. Omitted fields come from the onboarding’s saved account, or the recipient default if the onboarding has no saved bank record. If the onboarding shows no bank account, send a complete account. For example, a store changes its payout account from A to B. Zoop confirms B, but Pagar.me does not confirm the change. Yuno keeps B for Zoop, preserves Pagar.me’s previous saved account, and updates the recipient default to B. The request returns an error describing the outcomes. An error does not mean every provider stayed unchanged. Successful provider changes are not rolled back. The recipient default advances after at least one provider confirms the update. If every attempted provider refuses or has an unknown result, the old default remains. When there is no eligible provider-bound target, the account can be saved locally. Reading a saved account from Yuno is not an independent confirmation of an unknown provider outcome. Bank updates do not apply to onboardings in ERROR, BLOCKED, CANCELLED, INACTIVE, TRANSFERRED or TERMINATED. Targeting one of them (with onboarding_id, Update Onboarding or Continue Onboarding) returns 400 INVALID_STATE; a recipient-level update without onboarding_id skips them and keeps their previous account.

Bank errors and retries

Response	Meaning	Action
`400 INVALID_PARAMETERS`	The account is incomplete or invalid, or a provider explicitly refused it. A multi-provider request can still have applied to another provider.	Read all outcome messages and correct the indicated fields.
`400 INVALID_STATE`	The targeted onboarding is in a status that does not accept bank updates. No provider request is sent.	Do not retry the bank update on this onboarding.
`400 REQUEST_CANNOT_BE_PROCESSED`	Either bank-update admission was unavailable and no provider request was sent, or at least one provider confirmed the bank (listed as `APPLIED` in the messages) and a later non-bank update failed.	If a provider is listed as `APPLIED`, do not resend the bank; resubmit only the remaining non-bank changes. Otherwise retry the same intended request.
`400 OPERATION_NOT_SUPPORTED_BY_PROVIDER`	Without `onboarding_id`, the recipient also has an onboarding whose provider does not support bank updates. Supported providers listed as `APPLIED` were updated.	Read the outcome messages. To change only a supported provider, send `onboarding_id`.
`409 PROVIDER_TIMEOUT_AMBIGUOUS`	At least one result is unconfirmed. This can include provider refusals that the connector cannot distinguish from an uncertain write.	Read the outcome messages first. If they say the provider created the account but did not make it the settlement account, or that the settlement account changed, correct it at the provider instead of resending. Otherwise inspect the provider account before submitting a different bank, and resend the same intended account after the approximately three-minute cooldown.
`409 ONBOARDING_OPERATION_IN_PROGRESS`	Another operation holds the account, or one or more targets could not be attempted.	Follow the response guidance and retry the same intended request.

The cooldown reduces overlapping operations; it does not guarantee that a late provider write has finished. Do not retry automatically with a different account. Diagnostic messages can identify safe field names while omitting sensitive provider details. In a request containing both bank and other recipient fields, Yuno processes the bank first. When provider updates are attempted, the other fields are processed only after at least one provider confirms the bank. Yuno can still return an error for the remaining providers. Confirmed bank changes are not rolled back if a later non-bank update fails. Bank results do not themselves change onboarding lifecycle status. Providers can independently send onboarding events after a bank change, so an onboarding webhook may still arrive.

Authorizations

public-api-key

string

header

default:<Your public-api-key>

required

private-secret-key

string

header

default:<Your private-secret-key>

required

Path Parameters

recipient_id

string

required

The unique identifier of the recipient

Body

application/json

onboarding_id

string<uuid>

ID of an existing onboarding belonging to the recipient. When set, the identity fields sent in this request (e.g. first_name, email, phone, address) are stored as a per-onboarding override for that onboarding only, without modifying the shared recipient; when omitted, the update applies to the shared recipient and propagates to all non-terminal onboardings. Request-only, not returned in responses or webhooks.

Example:

"1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"

merchant_recipient_id

string

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

first_name

string

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

last_name

string

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

date_of_birth

string

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

entity_type

enum<string>

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

Available options:

GOVERNMENTAL,

PUBLIC,

NON_PROFIT,

PRIVATE

website

string

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

industry

string

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

merchant_category_code

string

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

string

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

phone

object

Show child attributes

address

object

Show child attributes

withdrawal_methods

object[]

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

split_configuration

object

Rules for automatic split calculation at the recipient level.

Show child attributes

Response

Recipient updated successfully

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

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

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[] | null

Rules for automatic split calculation at the recipient level. Returned as an array that holds the current split rule, even though requests send split_configuration as an object. null when no split configuration is set.

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"

⌘I

curl --request PATCH \
  --url https://api-sandbox.y.uno/v1/recipients/{recipient_id} \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "email": "newemail@example.com",
  "phone": {
    "country_code": "57",
    "number": "9876543210"
  }
}
'

{
  "id": "9104911d-5df9-429e-8488-ad41abea1a4b",
  "account_id": "9104911d-5df9-429e-8488-ad41abea1a4b",
  "merchant_recipient_id": "AAAA01",
  "national_entity": "INDIVIDUAL",
  "first_name": "John",
  "last_name": "Doe",
  "email": "newemail@example.com",
  "country": "CO",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:45:00Z"
}

Getting Started

Reference

Customers

Network Tokens

Customer Sessions (Enrollment)

Checkout Sessions

Payment Methods (Checkout)

Checkout Builder

Payment Methods (Direct Workflow)

PCI Proxy

Payments

Pre-Debit Notifications

3DS2 Setup

Unreferenced Refunds

Dry-run

Transaction Reporting

Routing Recommendations

Payment Links

Recipients for Marketplace

Sellers (Franchise)

Subscriptions Plans

Subscriptions

Payouts

Organizations

Reports

Installments

AI Caller

Communications Campaigns

Conversion Rate

FX Rates

Banking Connectivity

Webhooks

Bank-account updates

Bank errors and retries

Authorizations

Path Parameters

Body

Response

​Bank-account updates

​Bank errors and retries

Authorizations

Path Parameters

Body

Response

Bank-account updates

Bank errors and retries