Skip to main content

​
Overview

When an account is configured for the Ripio KYC flow, the partner does not collect KYC data directly. Instead:
  1. The partner calls the KYC endpoint with a redirectUrl.
  2. The API returns a providerUrl pointing to Ripio’s KYC platform.
  3. The user is redirected there to complete the identity verification.
  4. Ripio’s backend processes the result automatically.
  5. 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"
}
FieldDescription
submissionIdUnique identifier for this KYC submission. Save it to check status later.
providerUrlURL to redirect the user to Ripio’s KYC platform.
createdAtTimestamp of the submission creation (UTC).

​
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"
}
StatusDescription
IN_REVIEWKYC has been submitted and is under review.
COMPLETEDKYC has been approved. The customer can proceed.
FAILEDKYC 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.