Skip to main content
Every customer must complete identity verification (KYC) before they can operate. A customer’s KYC status must be COMPLETED before you can create On-Ramp or Off-Ramp orders. There are two ways to run KYC. This page helps you pick the right one; each model has its own step-by-step page.

​
The two models

Ripio-hosted KYC (redirect)

You send the user to Ripio’s KYC platform via a redirect. Ripio collects the data and documents. Simplest to integrate.

Partner-submitted KYC (API)

You collect the KYC fields in your own UI and submit them through the API. Maximum control over the experience.

​
Which model should you use?

In both models the user is redirected to a third-party provider for document upload and liveness checks. The difference is who collects the personal data beforehand.

​
Shortcut: reuse an existing Ripio KYC

If the customer already has an approved KYC with Ripio, you don’t need to collect anything — you can verify them with a one-time password (OTP) sent to their email. Always check for this first; it’s the fastest path. This shortcut is documented inside Partner-submitted KYC (API).

​
Reusable KYC (Sumsub share token)

If your customers are already verified in your own Sumsub account, you can share that verification with Ripio instead of putting the customer through the whole process again. You send a Sumsub share token when creating the KYC, Ripio redeems it, and — when both verifications are compatible — the customer skips the document upload and liveness check.
Reusable KYC is an opt-in feature that must be enabled for your account by the Ripio team. It is disabled by default. While it is disabled, any request that includes kycProviderShareToken returns 403 Forbidden with the error code 20065 (KycProviderTokenSharingNotEnabledException) and no KYC is created. Contact the Ripio team to have reusable KYC enabled for your account before integrating it.

​
How to use it

Add the root-level kycProviderShareToken field to Submit KYC Information. It works with both models — on its own for the Ripio-hosted redirect flow, or alongside a full kycSubmission body for the partner-submitted API flow.
The response is the same as any other KYC submission (submissionId, providerUrl, createdAt), and you track the outcome the same way: poll Retrieve KYC Submission or subscribe to KYC Events.

​
Things to keep in mind

  • Reuse is not guaranteed — it depends on Sumsub compatibility. Sumsub only transfers the verification steps that overlap between your level and Ripio’s, and it re-checks the shared documents against Ripio’s rules (accepted document types, issuing country, expiry). If the levels have no matching steps the reuse is rejected; if a re-check fails, the customer is asked for the missing documents. Skipping the flow entirely is the best case, not a certainty — see Sumsub’s Reusable KYC share documentation.
  • Share tokens are short-lived (Sumsub’s default is 20 minutes). Generate the token immediately before calling the endpoint, not ahead of time.
  • The token is only used when a new verification is opened. If a verification is already in progress for that customer, the call is idempotent and the token is ignored.
  • One token per customer. The share token must belong to the same person you are creating the KYC for.
  • API integration only. This field is not part of the Widget integration, and it does not apply to the OTP shortcut, which reuses a KYC the customer already has with Ripio rather than with you.

​
Where KYC fits in the flow

KYC happens after creating the customer and accepting the Terms & Conditions, and before creating any order:
See the On-Ramp and Off-Ramp walkthroughs for the full sequence.

​
KYC statuses

Instead of polling, you can subscribe to KYC Events to be notified when a customer’s status changes.