> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ripio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC with Ripio

> Delegated KYC flow where the partner initiates the process and the user completes identity verification directly on Ripio's platform.

## 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](/ramps-api/kyc/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.

<Warning>
  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.
</Warning>

***

## Step 1 — Initiate the KYC process

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

```bash theme={null}
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:**

```json theme={null}
{
  "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).                               |

***

## 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.

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

**Response:**

```json theme={null}
{
  "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](/ramps-api/webhooks/kyc-events) for the full payload reference.