Card KYC overview
The Card KYC endpoints verify a customer who will get a card. The hosted flow captures a liveness check, which card activation needs. Card KYC and the KYC API share one KYC result, so basic KYC completed in either flow counts for both. The /v1/risk/ routes serve cards only.
Start a cardholder verification or browse the operations in this category.
Review the cardholder verification flow before integrating.
Which flow to use
| You want to | Use |
|---|---|
| Verify a customer for accounts, transfers and other products | The KYC API |
| Verify a future cardholder with liveness in the same step | POST /v1/risk/start-kyc |
| Activate cards for a customer already verified | POST /v1/risk/features/activate, which returns a liveness link when one is still needed |
If you call POST /v1/risk/start-kyc for a customer whose KYC status is anything other than not_started, including completed, it resets their KYC to pending until the review finishes again. Never call it for a verified customer.
Endpoints
| Endpoint | Description |
|---|---|
POST /v1/risk/start-kyc |
Start hosted verification with liveness and get a link valid for one hour |
POST /v1/risk/upload-document |
Upload a base64-encoded document. Validation errors return HTTP 200 with data.status error |
POST /v1/risk/start-kyc-s2s |
Submit uploaded documents. Missing documents return HTTP 200 with data.code MISSING_DOCUMENTS |
Read the outcome from the customer's basic KYC status on GET /v1/customers/{customer_id}, or from a customer.kyc.status.completed or customer.kyc.status.failed webhook. Other errors return HTTP 400 with a message in error.
Authentication
All requests use https://api.gravv.xyz/v1/ and authenticate with the Api-Key header. See Authentication for details.