Ripio-hosted KYC (redirect)

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

Overview

When an account is configured for the Ripio KYC flow, the partner does not collect KYC data directly. Instead:

The partner calls the KYC endpoint with a redirectUrl.
The API returns a providerUrl pointing to Ripio’s KYC platform.
The user is redirected there to complete the identity verification.
Ripio’s backend processes the result automatically.
The partner can poll the submission status endpoint to check the outcome.

This flow differs from the API flow, where the partner manages their own UI, collects the KYC fields, and submits them directly via the API (see Submit KYC Information). In both cases the user is still redirected to a third-party provider for document upload and liveness checks — the difference is who collects the personal data beforehand.

This flow is only available in production. In sandbox, the KYC is approved automatically and no providerUrl will be returned — Steps 2 and 3 can be skipped when testing.

Step 1 — Initiate the KYC process

Call POST /api/v1/customers/{customerId}/kyc/ with only the redirectUrl. No kycSubmission body is required.

curl --request POST \
  --url https://{baseUrl}/api/v1/customers/{customerId}/kyc/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "redirectUrl": "https://www.example.com/"
  }'

Response:

{
  "submissionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "providerUrl": "https://kyc.ripio.com/?token=eyJhbGci...&id=17813&schema=B2B_AR",
  "createdAt": "2024-01-15T10:30:00Z"
}

Field	Description
`submissionId`	Unique identifier for this KYC submission. Save it to check status later.
`providerUrl`	URL to redirect the user to Ripio’s KYC platform.
`createdAt`	Timestamp of the submission creation (UTC).

If the customer is already verified in your own Sumsub account, you can add a kycProviderShareToken to this request so Ripio reuses that verification 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; while it is disabled, sending the field returns 403 with the error code 20065. See Reusable KYC (Sumsub share token).

Step 2 — Redirect the user

Redirect the user’s browser to the providerUrl returned in Step 1. The user will complete the identity verification process on Ripio’s KYC platform. Once finished, Ripio redirects the user back to the redirectUrl you provided.

Step 3 — Ripio processes the KYC

Ripio’s backend processes the KYC result automatically. No action is required from the partner at this stage.

Step 4 — Check the submission status

Poll GET /api/v1/customers/{customerId}/kycSubmissions/ to check the current status of the KYC.

curl --request GET \
  --url https://{baseUrl}/api/v1/customers/{customerId}/kycSubmissions/ \
  --header 'Authorization: Bearer <token>'

Response:

{
  "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "COMPLETED",
  "createdAt": "2024-01-15T10:30:00Z"
}

Status	Description
`IN_REVIEW`	KYC has been submitted and is under review.
`COMPLETED`	KYC has been approved. The customer can proceed.
`FAILED`	KYC was rejected.

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.

Overview

Widget integration

API Integration

Ripio-hosted KYC (redirect)

Overview

Step 1 — Initiate the KYC process

Step 2 — Redirect the user

Step 3 — Ripio processes the KYC

Step 4 — Check the submission status

Webhooks

​Overview

​Step 1 — Initiate the KYC process

​Step 2 — Redirect the user

​Step 3 — Ripio processes the KYC

​Step 4 — Check the submission status

​Webhooks

Overview

Step 1 — Initiate the KYC process

Step 2 — Redirect the user

Step 3 — Ripio processes the KYC

Step 4 — Check the submission status

Webhooks