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. It takes no request body — the check always runs against the email already stored on the customer. If the customer has no email yet, set one with Update Customer before calling it.
  • 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, with the catalogs for every CHOICE field. KYC fields by country explains what each field means and what format it takes.
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.
The whole payload is validated before the verification is opened: formats, catalog values and cross-field rules. A bad value returns 400 with error code 20000. Which fields are required, and what format each takes, differs per country — see KYC fields by country.The offending field is named in the response, nested under kycSubmission:
A 400 here means nothing was created: no verification is opened and the customer’s KYC is not consumed. Correct the field and repeat the same call.
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.