Skip to main content
Not sure which KYC model to use? Start with Overview & which model to use.

​
How it works

In this model you collect the KYC fields in your own UI and submit them through the API. The recommended starting point is always to check whether the customer already has an approved KYC with Ripio — if they do, you can reuse it via OTP and skip data collection entirely.
If the customer is already verified in your own Sumsub account, you can share that verification with Ripio instead of running a new one: send a Sumsub share token in kycProviderShareToken and, if the two verifications are compatible, the customer skips the document upload and liveness check. This is an opt-in feature that must be enabled for your account by the Ripio team — see Reusable KYC (Sumsub share token).

​
Step 1 — Check if the customer already has KYC with Ripio

Call Check KYC Status & Send OTP. You can pass the customer’s email in the body, or omit the body entirely to use the email already stored on the customer.
  • If they do → 200, and an OTP is sent to their email. Continue with the OTP reuse flow.
  • If they don’t → 400 KycNotApprovedException. Proceed with the full KYC submission flow.
  • If the customer is already verified on your integration → 400 KycAlreadyApprovedException, and no OTP is sent. Nothing left to do: skip KYC entirely and go on to the quote.
Since the last two outcomes are both HTTP 400, branch on the error’s type field rather than on the status code.

​
KYC reuse via OTP

The customer already has an approved KYC with Ripio. No document upload required.
1

Validate OTP

Call Validate OTP with the code the customer received. On success, the KYC is approved for this customer in your platform.

​
Full KYC submission

The customer has no prior KYC with Ripio.
1

Get KYC requirements

Call Retrieve KYC Requirements to get the fields required for your account’s country.
2

Submit KYC data

Call Submit KYC Information with the customer’s data. The response includes a providerUrl — redirect the user there to complete document upload and liveness check.If reusable KYC is enabled for your account, add kycProviderShareToken to this same request to reuse a verification the customer already completed in your Sumsub account. Sending the field without the feature enabled returns 403 with the error code 20065.
3

Check submission status

Call Retrieve KYC Submission to poll the result. Once status is COMPLETED, the customer is verified and can operate.

​
Webhooks

Instead of polling, you can configure a webhook URL to receive real-time notifications whenever a customer’s KYC status changes. See KYC Events for the full payload reference.