KYC API
KYC (Know Your Customer) verification is required before customers can place orders. The API supports multiple KYC providers including KYCAID and Ondato.
Start KYC
Initiate a KYC verification flow for a customer.
Endpoint
Request Body
| Parameter | Type | Required | Description |
|---|
customerId | string | Yes | Customer ID |
redirectUrl | string | No | URL to redirect after KYC completion |
tier | string | No | KYC tier level (default: “basic”) |
Example Request
curl -X POST https://api.nowramp.com/v1/kyc-cases \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_abc123",
"redirectUrl": "https://partner-app.com/kyc-complete"
}'
Response
{
"success": true,
"data": {
"id": "kyc_case_xyz789",
"customerId": "cust_abc123",
"status": "pending",
"verificationUrl": "https://kyc-provider.com/verify/abc123",
"expiresAt": "2024-01-16T10:00:00Z",
"createdAt": "2024-01-15T10:00:00Z"
}
}
Redirect the customer to verificationUrl to start the KYC process. The URL expires after 24 hours.
Get KYC Case
Retrieve a KYC case by ID.
Endpoint
GET /v1/kyc-cases/{kycCaseId}
Example Request
curl https://api.nowramp.com/v1/kyc-cases/kyc_case_xyz789 \
-H "X-API-Key: your_api_key"
Response
{
"success": true,
"data": {
"id": "kyc_case_xyz789",
"customerId": "cust_abc123",
"status": "approved",
"tier": "basic",
"result": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1990-01-15",
"country": "US",
"documentType": "passport",
"verifiedAt": "2024-01-15T10:30:00Z"
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
}
Get Customer KYC Status
Get the current KYC status for a customer.
Endpoint
GET /v1/customers/{customerId}/kyc
Example Request
curl https://api.nowramp.com/v1/customers/cust_abc123/kyc \
-H "X-API-Key: your_api_key"
Response
{
"success": true,
"data": {
"status": "approved",
"tier": "basic",
"currentCase": {
"id": "kyc_case_xyz789",
"status": "approved",
"completedAt": "2024-01-15T10:30:00Z"
},
"canTransact": true
}
}
List KYC Cases
List KYC cases for a customer.
Endpoint
GET /v1/customers/{customerId}/kyc-cases
Example Request
curl https://api.nowramp.com/v1/customers/cust_abc123/kyc-cases \
-H "X-API-Key: your_api_key"
KYC Statuses
| Status | Description |
|---|
pending | KYC case created, awaiting customer |
in_progress | Customer is completing verification |
manual_review | Under manual review |
approved | KYC approved |
rejected | KYC rejected |
expired | Verification link expired |
KYC Tiers
Different tiers have different verification requirements and transaction limits:
| Tier | Requirements | Daily Limit |
|---|
basic | ID + Selfie | $1,000 |
standard | Basic + Proof of Address | $10,000 |
enhanced | Standard + Source of Funds | $100,000 |
Tier requirements and limits are configurable per project. Contact support to adjust.
KYC Providers
KYCAID (Default)
- Fast verification (typically < 5 minutes)
- 190+ countries supported
- Document types: Passport, ID card, Driver’s license
Ondato
- EU-focused provider
- Video verification available
- Document types: Passport, ID card, Residence permit
KYC providers are configured by the NowRamp team during your onboarding process. Contact support if you need to change your KYC provider.
Webhooks
KYC events trigger webhooks:
kyc.started - Customer began verificationkyc.approved - KYC approvedkyc.rejected - KYC rejectedkyc.expired - Verification link expiredkyc.manual_review - Sent to manual review
Rejection Reasons
| Code | Description |
|---|
document_expired | ID document has expired |
document_unreadable | Document quality too low |
face_mismatch | Selfie doesn’t match ID |
document_fraud | Suspected fraudulent document |
underage | Customer is under 18 |
country_restricted | Country not supported |
