KYC

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

The flow

Every call is under /partner/users/:user_code/kyc/. Always start by reading the status — it tells you the exact next step, so the flow resumes cleanly if a user drops off.

When a user is approved

Check status

Drive your UI off v2.nextStep. It is the one field you need; the rest is detail.

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

Test mode returns the same shape, plus simulated: true.

Stage 1 — email

Failures come back as errors, not as success: true — for example 400 DISPOSABLE_EMAIL, or 400 INVALID_CODE for a wrong or expired code. Show error.message to the user.

Stage 2 — PAN

An instant check against the income-tax record. The email must be verified first.

curl -X POST https://api.oropocket.com/partner/users/usr_xxx/kyc/pan/verify \
  -H "Authorization: Bearer oro_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"pan":"ABCPK1234Z","dateOfBirth":"1990-08-15","nameAsPerPan":"ASHA KUMARI"}'

Stage 2b — PAN photo (fallback only)

Only open when v2.panPhotoAllowed is true: after the instant check hit a service outage, or the user failed it twice. Otherwise it answers 400 PAN_PHOTO_NOT_ALLOWED. A PAN photo always means the KYC ends in OroPocket's review.

Stage 3a — Aadhaar by DigiLocker (recommended)

DigiLocker is the Government of India's document wallet. The user signs in there (mobile number or Aadhaar, plus an OTP from DigiLocker) and taps Allow to share their Aadhaar with OroPocket. The PAN step must be done first.

Calling it again within about 12 minutes returns the same session, so a double tap doesn't start two.

Opening the url. Use one of these:

returnUrl. When the user finishes, the browser goes to your returnUrl with ?session_id=<id>&status=<status> appended. Treat status there as a hint only — confirm with the GET below or the webhook before you show success. The origin must be listed in your panel under Payments → Checkout → Return origins (the same list payment returns use; if you don't see Payments in your panel, ask your OroPocket contact to add the origin). Without a returnUrl, the user sees "DigiLocker step complete — go back to the app", which suits an in-app browser you close yourself.

Polling or webhooks? Webhooks are the reliable signal: kyc.approved or kyc.under_review fires when the session ends well. If you want an immediate answer when the user lands on your returnUrl (or closes the in-app browser), call the GET once, then every 3 seconds or so while it says pending — and stop after a couple of minutes.

# 1) start a session
curl -X POST https://api.oropocket.com/partner/users/usr_xxx/kyc/aadhaar/digilocker \
  -H "Authorization: Bearer oro_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"returnUrl":"https://app.example.com/kyc/done"}'

# 2) after the user comes back, read the outcome
curl https://api.oropocket.com/partner/users/usr_xxx/kyc/aadhaar/digilocker/9b2c4e7a1f0d5c38e6a4b1d27f90c3e5 \
  -H "Authorization: Bearer oro_live_xxx"

Stage 3b — Aadhaar photos

For users without DigiLocker, or when it isn't working. The KYC goes to OroPocket's review (usually within 24–48 h) and you hear back by kyc.approved or kyc.rejected.

curl -X POST https://api.oropocket.com/partner/users/usr_xxx/kyc/aadhaar/photos \
  -H "Authorization: Bearer oro_live_xxx" \
  -H "Content-Type: application/json" \
  -d "{\"aadhaarNumber\":\"234567890124\",\"front\":\"$(base64 -w0 front.jpg)\",\"back\":\"$(base64 -w0 back.jpg)\"}"

After a rejection

kyc.rejected carries the reviewer's message in data.reason (also in rejectionReason on the status). The user can start again: read the status and follow v2.nextStep. Webhook payloads and the kyc.under_review reason codes are on Webhooks.

The older manual path

POST kyc/details (fullName, aadharNumber, panNumber, dateOfBirth, optional address) followed by POST kyc/documents (publicly fetchable panImageUrl, aadharFrontImageUrl, aadharBackImageUrl) still works and ends in review, but it is no longer recommended — use the PAN and Aadhaar steps above. If you already hold a user's verified PAN and Aadhaar record, see Submit collected KYC.

Testing it

With an oro_test_ key nothing real is checked and no real documents are needed.

Webhooks fire in test mode too, with data.mode: "sandbox". Try every call from the Playground; more on test mode in Sandbox.