Copy page

v2

Quickstart

This procedure sends a User Verification v2 request and checks the remaining quota.

Before you begin

Obtain these credentials from Privy:

• Basic authentication username and password.
• Confidential merchant key.

Use the staging environment while you build and test the integration.

1. Prepare the images

Encode the original selfie and identity-card images as base64 strings. Each decoded image must be no larger than 2 MB and must be a JPG, JPEG, or PNG. The selfie must be 135–1080 px wide and 240–1920 px high. The KTP image must be 480–1920 px wide and 270–1080 px high.

Send only the base64 value. Do not include a data-URL prefix such as data:image/jpeg;base64,.

2. Verify the user

Send the request from the merchant backend:

Code
curl -X POST https://stg-b2b-api.privy.id/api/v2/userverification \
  -H 'Authorization: Basic <BASE64_USERNAME_PASSWORD>' \
  -H 'Merchant-Key: <MERCHANT_KEY>' \
  -H 'Privy-Version: 2026-08-17.heimdall' \
  -H 'Content-Type: application/json' \
  -d '{
    "trId": "b0e932f0-50c1-419d-a32f-ad49c3a6906b",
    "nik": "3421000999092323",
    "name": "Saswoluyo",
    "dob": "07-10-1998",
    "email": "example@mail.com",
    "phone": "+6289998887777",
    "selfie": "<BASE64_SELFIE>",
    "ktp": "<BASE64_KTP>",
    "channel": "chrome"
  }'

A verified response has this form:

Code
{
  "code": 200,
  "status": "ok",
  "userStatus": "verified",
  "privy_id": "ABC1234",
  "balance": 13,
  "transaction_id": "deabaaa2-73a1-46a6-9794-45d14a3be4f6",
  "message": "digital certificate has been issued"
}

If userStatus is rejected, the response also contains rejected_code and the digital certificate is held. See Verification results.

3. Check the quota

Use the same credentials to read the remaining quota:

Code
curl https://stg-b2b-api.privy.id/api/v1/quota/user-verification \
  -H 'Authorization: Basic <BASE64_USERNAME_PASSWORD>' \
  -H 'Merchant-Key: <MERCHANT_KEY>'

The response returns the balance as a string:

Code
{
  "code": 200,
  "balance": "12",
  "service": "user-verification"
}