KYC

Verify a user's identity so they can withdraw INR, gift assets or take physical delivery. All capability `kyc`.

KYC is required before a user can withdraw, gift or take physical delivery. Buying, selling and *receiving* gifts do not require it.

KYC is global, not per-partner: a user verified anywhere on OroPocket is verified everywhere. See sub-wallets.

The flow

Four ordered stages. Always start by reading the status — it tells you the exact next step, so the flow is resumable if a user drops off.

Stage	What it means
email_verification	Confirm the user's email with a 6-digit code. Always first.
personal_details	Identity data — either instantly via PAN + Aadhaar, or manually.
document_upload	Manual path only: PAN and Aadhaar images.
admin_review	Manual path only: a human reviews within 24–48h.

There are two routes through it. Instant KYC (PAN + Aadhaar OTP) auto-approves in seconds and is the recommended path when automatedKyc.enabled is true. Manual upload is the fallback.

Check status

GET/partner/users/:user_code/kyc/statuskyc

Field	Type	Description
status	string	not_started \| under_review \| approved \| rejected.
nextStep	string \| null	What to do next: email_verification, personal_details, document_upload, awaiting_review, resubmit_documents, or null when done. Drive your UI off this.
steps	object	Per-stage {completed, label, order, pending}.
completionPercentage	number	0–100, for a progress bar.
verificationLevel	string	"full" once approved.
emailVerified	boolean	Stage 1 done.
detailsSubmitted	boolean	Stage 2 done.
documentsUploaded	boolean	Stage 3 done (manual path).
rejectionReason	string \| null	Why a rejection happened.
canResubmit	boolean	True after a rejection — the user may try again.
automatedKyc.enabled	boolean	Whether instant PAN + Aadhaar KYC is available.

curl https://api.oropocket.com/partner/users/usr_xxx/kyc/status \
  -H "Authorization: Bearer oro_live_xxx"

Stage 1 — email

POST/partner/users/:user_code/kyc/email/sendkyc

Field	Type		Description
email	string	required	Must not already belong to another OroPocket account.

Field	Type	Description
sent	boolean	Code dispatched.
expires_in_seconds	number	600 (10 minutes).

POST/partner/users/:user_code/kyc/email/verifykyc

Field	Type		Description
verification_code	string	required	The 6-digit code (alias: "code"). 123456 in sandbox.

Field	Type	Description
verified	boolean	Success.
nextStep	string	The following stage.

Stage 2a — instant KYC (recommended)

Two calls, and the user is approved — no documents, no human review.

POST/partner/users/:user_code/kyc/pan/verifykyc

Field	Type		Description
pan	string	required	Format AAAAA9999A.
dateOfBirth	string	required	YYYY-MM-DD — must match the income-tax record for that PAN.
nameAsPerPan	string	optional	Improves the name match.

Field	Type	Description
panVerified	boolean	PAN matched.
autoApproved	boolean	Still false here — approval happens after Aadhaar.
nextStep	string	"aadhaar_otp".

Errors: 403 FEATURE_DISABLED if instant KYC is off for your profile, 429 RATE_LIMITED, or 400 on a wrong PAN/DOB combination.

POST/partner/users/:user_code/kyc/aadhaar/otp/sendkyc

Field	Type		Description
aadhaarNumber	string	required	12 digits.

Field	Type	Description
aadhaarLast4	string	For display.
otpValidForSeconds	number	600.
resendAfterSeconds	number	45.

POST/partner/users/:user_code/kyc/aadhaar/otp/verifykyc

Field	Type		Description
otp	string	required	6-digit Aadhaar OTP (1234 in sandbox).

Field	Type	Description
aadhaarVerified	boolean	Aadhaar matched.
autoApproved	boolean	True when PAN and Aadhaar identities agree.
kycStatus	string	"approved" on success.
verificationLevel	string	"full".
profile	object	{name, dateOfBirth, gender, address, aadhaarLast4} pulled from Aadhaar.

If the PAN and Aadhaar identities don't match, the user lands in under_review instead of being approved — handle that state.

Stage 2b — manual fallback

Use this when instant KYC is unavailable or the user's documents don't match.

POST/partner/users/:user_code/kyc/detailskyc

Field	Type		Description
fullName	string	required	As per documents.
aadharNumber	string	required	12 digits. Must be unique across OroPocket.
panNumber	string	required	AAAAA9999A. Must be unique across OroPocket.
dateOfBirth	string	required	YYYY-MM-DD.
addressLine1	string	optional	Street address.
addressLine2	string	optional
city	string	optional
state	string	optional
pincode	string	optional	6 digits.

POST/partner/users/:user_code/kyc/documentskyc

All three URLs are required and must be publicly fetchable. This moves the user to under_review.

Field	Type		Description
panImageUrl	string	required	PAN card image.
aadharFrontImageUrl	string	required	Aadhaar front.
aadharBackImageUrl	string	required	Aadhaar back.

Field	Type	Description
status	string	"under_review" — a human reviews within 24–48h.

Testing it

Sandbox value	Result
PAN ABCDE1234F	Verifies successfully.
PAN ZZZZZ9999Z	Rejected — use this to test your failure path.
Aadhaar OTP 1234	Verifies.
Email code 123456	Verifies.

No real documents are ever needed in sandbox — you can exercise both the approve and reject paths end to end.

← Sub-wallets Bank & withdrawals →