KYC & Verification

VaultsPay handles all KYC (“Know Your Customer”) checks for you — Emirates ID verification, liveness, sanctions screening and PEP checks.

Lifecycle

pending → in_review → approved
                  ↘
                    rejected

pending — user created, waiting for documents.
in_review — documents uploaded, VaultsPay is verifying.
approved — user can open accounts and be issued cards.
rejected — verification failed. Inspect kyc.reason for details.

You receive user.kyc.status_changed webhook events on each transition.

Start a KYC session

POST/v1/users/{id}/kyc_sessions

Body

Field	Type	Description
`level`required	enum	basic \| full. `full` is required for card issuance.
`redirect_url`	string	URL to redirect the user after they complete the hosted KYC flow.
`locale`	string default: en	UI language — en \| ar.

Request

curl -X POST https://api.vaultspay.ae/v1/users/usr_01HX7.../kyc_sessions \
  -H "Authorization: Bearer sk_test_yourApiKeyHere" \
  -H "Content-Type: application/json" \
  -d '{
    "level": "full",
    "redirect_url": "https://yourapp.com/onboard/complete",
    "locale": "en"
  }'

Response

201 Created

{
  "id": "kyc_01HX78XABCDE...",
  "object": "kyc_session",
  "user_id": "usr_01HX7...",
  "level": "full",
  "status": "created",
  "hosted_url": "https://kyc.vaultspay.ae/s/abc123def456",
  "expires_at": "2026-04-25T14:52:03Z"
}

Redirect your user to hosted_url. Once they complete the flow, they’re redirected back to redirect_url and you’ll receive a user.kyc.status_changed webhook.

Retrieve a KYC session

GET/v1/users/{id}/kyc_sessions/{session_id}

curl https://api.vaultspay.ae/v1/users/usr_.../kyc_sessions/kyc_... \
  -H "Authorization: Bearer sk_test_yourApiKeyHere"

Supported document types

Type	Field name	Notes
Emirates ID	`emirates_id`	Front + back required.
Passport	`passport`	Biographical page only.
Address proof	`address_proof`	Utility bill or bank statement < 3 months.
Selfie	`selfie`	Captured live during KYC session.

Delete User Upload Documents