Skip to main content
PATCH
Update onboarding
Updates an existing onboarding for a recipient. Only specified fields will be updated. This endpoint updates an existing onboarding for a recipient, allowing you to modify onboarding details after initial creation. Use this when you need to update provider information, documentation, banking details, or other onboarding parameters for existing recipients in the split payments marketplace.

Prerequisites

This endpoint requires an existing onboarding created via Create Onboarding

Updating a bank account

For Zoop and Pagar.me onboardings with a provider recipient ID, an explicit withdrawal_methods.bank update waits for the provider result. It updates only the selected onboarding; the recipient default and other onboardings remain unchanged. Only a confirmed account is saved for the onboarding. Bank-update results do not change its lifecycle status. Send a complete account when the onboarding shows no bank account. See bank errors and retries for partial outcomes, 400 responses and 409 reconciliation guidance. For these supported provider-bound onboardings, non-bank fields other than documentation are saved in Yuno without a separate provider profile update. Sending a description or metadata does not resend the saved bank account. In a mixed request, the bank is processed first; other fields are saved only after it succeeds. Previously onboarded recipients retain the existing status notification for non-bank updates without documentation. For example, changing only a store’s description leaves its confirmed payout account and onboarding status unchanged. To change the payout account, include withdrawal_methods.bank explicitly.

Updating documentation

For Zoop onboardings with a provider recipient ID, a request with documentation sends the documents in that request to Zoop and waits for the result. This includes previously onboarded recipients. Only the document categories in the request are sent, and the bank account is not resent.
  • If Zoop accepts the documents, the onboarding takes the status and requirements that Zoop reports, and the usual onboarding webhook is sent.
  • If Zoop rejects the documents, or the delivery or the resulting status cannot be confirmed, the response is 400 with code PROVIDER_OPERATION_FAILED. The documents are saved in Yuno, and the onboarding keeps its previous status and requirements. Resend only documentation.
  • In a request that also updates the bank account, the bank update is processed first. If the documents then fail, the 400 also reports the bank result. A bank change reported as APPLIED stays applied, so resend only documentation.
Onboardings in CANCELLED, BLOCKED, INACTIVE or TRANSFERRED status reject updates with 400 INVALID_STATE, except previously onboarded recipients: their update saves documentation in Yuno without sending it to the provider. A TERMINATED onboarding always returns 400 INVALID_STATE.

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

ID of the recipient whose onboarding will be updated

onboarding_id
string
required

ID of the onboarding to be updated

Body

application/json
account_id
string

Unique id of the account in Yuno

Example:

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

type
enum<string>

Type of onboarding flow. PREVIOUSLY_ONBOARDED for pre-existing accounts, ONE_STEP_ONBOARDING for account creation + KYC in one step, TWO_STEP_ONBOARDING for account creation first then KYC later

Available options:
PREVIOUSLY_ONBOARDED,
ONE_STEP_ONBOARDING,
TWO_STEP_ONBOARDING
Example:

"PREVIOUSLY_ONBOARDED"

workflow
enum<string>

Workflow of the onboarding

Available options:
HOSTED_BY_PROVIDER,
HOSTED_BY_YUNO,
DIRECT
Example:

"HOSTED_BY_PROVIDER"

callback_url
string<uri>

URL in case to redirect your customer after the onboarding process with the provider, if needed.

Example:

"https://www.google.com"

provider
object
documentation
object[]

Specifies the documentation object.

withdrawal_methods
object

Specifies the withdrawal methods object.

Object to indicate the owners of the organization. Adyen, Stripe and dlocal have fields related to that.

terms_of_service
object

Object describing terms of service.

Response

Updated

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"