Update Onboarding
Update the data or documentation of an existing recipient onboarding
Prerequisites
This endpoint requires an existing onboarding created via Create OnboardingPreviously onboarded accounts
To re-register an existingPREVIOUSLY_ONBOARDED onboarding, for example after it ended in ERROR because an account id was wrong, call PATCH /v1/recipients/{recipient_id}/onboardings/{onboarding_id} with the provider object: provider.id, provider.connection_id and the account ids.
provider.recipient_id, provider.recipient_additional_id, provider.balance_account_id, provider.legal_entity and provider.recipient_type. Which of them a provider needs is defined by its integration. They are forwarded exactly as sent.
- The integration supports adopting existing accounts: Yuno repeats the registration with the provider and applies its answer. The onboarding becomes
SUCCEEDED(webhookonboarding.succeeded), orERRORwith the provider’s message inresponse_message(webhookonboarding.error). An onboarding inERRORbecomesSUCCEEDEDonce the provider accepts the corrected ids. - Any other provider: the ids are stored and no call is made to the provider. They are not validated at the provider.
Updating a bank account
For Zoop and Pagar.me onboardings with a provider recipient ID, an explicitwithdrawal_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 withdocumentation 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
400with codePROVIDER_OPERATION_FAILED. The documents are saved in Yuno, and the onboarding keeps its previous status and requirements. Resend onlydocumentation. - In a request that also updates the bank account, the bank update is processed first. If the documents then fail, the
400also reports the bank result. A bank change reported asAPPLIEDstays applied, so resend onlydocumentation.
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
Path Parameters
Body
Type of onboarding flow. PREVIOUSLY_ONBOARDED attaches an account that already exists at the provider, ONE_STEP_ONBOARDING for account creation + KYC in one step, TWO_STEP_ONBOARDING for account creation first then KYC later.
To re-register a PREVIOUSLY_ONBOARDED onboarding, send provider.id, provider.connection_id and the provider account ids. When the provider integration supports adopting existing accounts, Yuno repeats the registration and applies the answer: the onboarding becomes SUCCEEDED or ERROR with the provider's message in response_message. For any other provider the ids are stored and no call is made to the provider. An update without provider ids only re-sends the notification of the current status. Which providers adopt existing accounts is Yuno-side configuration per environment; ask your Key Account Manager.
PREVIOUSLY_ONBOARDED, ONE_STEP_ONBOARDING, TWO_STEP_ONBOARDING "PREVIOUSLY_ONBOARDED"
Response
Updated