Skip to main content
Virtual bank accounts and pay-outs run through our banking partners. Before a partner issues bank details or accepts a pay-out destination for your customer, your customer has to be onboarded with that partner. That is partner onboarding, the last of three onboarding gates. How much that involves depends on the partner:
  • Some partners rely on Venly’s verification. The compliance checks happen on our side, through the identity verification your customer already completed.
  • Other partners run their own KYC or KYB. We pass on your customer’s verified data, and the partner reviews it before accepting them. Sometimes the partner needs more from your customer directly. requiredActions tells you when that happens.
When a verified customer still can’t be provisioned, this gate is the usual reason: creating a virtual bank account or a pay-out route answers 409 partner-onboarding-pending or 422 partner-onboarding-rejected. If that is where your customer is stuck, this page walks you through finding out why and what to do about it.

Rule out the other two gates

The gates are independent. A party can be VERIFIED, have ACCEPTED the terms, and still be PENDING with the partner. If either of the first two isn’t cleared, fix that first. Partner onboarding can’t start until the party is verified.

Read the partner-onboarding status

Response (200)
Reading is safe: it never triggers onboarding or provisioning. The status tells you which situation you are in: The same status is also on the party as partnerOnboardingStatus, so Get a party shows it too. requiredActions is only returned by this endpoint.

Not started: start onboarding

Onboarding starts the first time you try to provision. You can also start it yourself:
The call is asynchronous. It answers 202 with the same body as the read, normally PENDING, and you poll the read endpoint for the outcome. While onboarding is PENDING or APPROVED, calling it again changes nothing. If the party doesn’t qualify yet, you get a retryable 409: Partner onboarding is for individuals only. For an ORGANISATION you get 400 party-type-not-supported, and retrying won’t help.

Pending: is the partner waiting on your customer?

Look at requiredActions. It is always present:
  • Empty ([]): there is nothing for your customer to do right now. The partner is working on it, possibly reviewing something your customer already submitted. Keep polling; status moves on by itself.
  • Not empty: the partner can’t finish until your customer completes each listed step.
More reason values may be added. Treat an unknown value like IDENTIFICATION, and don’t fail on it. Each entry has a url to the partner’s hosted flow. Give it to your customer, who opens it and completes the step there. You don’t need to tell Venly when they’re done: once the partner approves, status moves to APPROVED by itself. The link can change between calls. It is resolved live on every read, which is why both partner-onboarding responses are sent with Cache-Control: no-store. Always use the one from your latest call, and never cache or store it.
The url works without a login, so treat it like a credential. Only give it to the end customer it belongs to: show it in their own session and don’t send it anywhere else. Never write it to logs.
A simple way to handle this in your product:
  1. Poll GET /parties/{partyId}/partner-onboarding.
  2. While status is PENDING and requiredActions is not empty, show your customer a “complete your verification” prompt that opens the latest url.
  3. Keep polling until status is APPROVED, then provision.

Rejected: retry once the cause is fixed

REJECTED is not final. Once the underlying problem is resolved, for example corrected details or a re-run verification, call POST again to re-attempt onboarding. You don’t need Venly for this. Provisioning answers 422 partner-onboarding-rejected until the party is approved.

Avoiding the wait next time

Call POST /parties/{partyId}/partner-onboarding as soon as a customer’s verification clears, while they are still in your onboarding flow. It is usually APPROVED by the time they ask for bank details. If the partner needs something from them, requiredActions shows it while they’re still there to act on it.

Next steps

Partner-terms consent

The gate that comes just before this one.

Virtual bank accounts

The first thing partner onboarding unblocks.

Troubleshooting verification

Which onboarding errors are worth retrying and which aren’t.

Onboarding lifecycle

All the states, from a new party to an account that can move money.