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. Collecting the data yourself does not skip the identity-provider step, though: the response from Submit KYC Information still includes a providerUrl, and you still redirect the customer to it. That page is Ripio’s own UI, which resolves the document-upload and liveness check with the identity provider inside a webview — “API” describes who collects the personal data beforehand, not that you build your own document-capture screen. Start with Start KYC — this is the first call for every verification under this model. If your account is also configured for Sumsub share-token reuse, include kycProviderShareToken in that same call (see Reusable KYC (Sumsub share token)).
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 works with this API model as well as the Ripio-hosted redirect model. It is an opt-in feature that must be enabled for your account by the Ripio team — see Reusable KYC (Sumsub share token).

​
The flow

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

Start KYC

Call Start KYC with redirectUrl. It takes no kycSubmission. If the customer has no email yet, set one with Update Customer before calling it.If reusable KYC is enabled for your account, this is where kycProviderShareToken goes — the token is redeemed in this same call, not in a later one. Start KYC is a mandatory step for the reusable KYC flow under this model: there is no other call that accepts the token here.The response’s otpRequired tells you what to do next:
  • true → continue with the next step.
  • false → no OTP left to validate. Check the response’s status: continue with Submit KYC Information if data is still missing, or move on to polling otherwise.
3

(Optional) Resend the OTP

If the customer didn’t get the email, or the code expired, call Resend KYC OTP.
4

Validate OTP

Call Validate KYC OTP with the code the customer received. In sandbox, 123456 always works — see KYC in sandbox.
  • The customer already has an approved KYC with Ripio → this call approves them immediately. Nothing else to do.
  • They don’t → the OTP is confirmed, but the KYC is not approved yet. Continue with Submit KYC Information to send the customer’s data.
Confirming the OTP only proves the customer owns that email — it does not by itself approve the KYC. Sending kycSubmission afterwards doesn’t guarantee approval either: it always depends on what the identity provider reports back, and if something needs to be corrected or re-verified, the flow reopens for the customer to complete it.
5

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.
kycProviderShareToken does not go here. If reusable KYC is enabled for your account, it was already redeemed in the Start KYC call above — if it resolved the customer’s identity, the document upload and liveness check are already covered by the time the customer reaches providerUrl.
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.
6

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.