Identity Verification API (age check)

One CP API in front of identity providers. Users in Korea go through a mobile identity check (NHN KCP); users elsewhere go through facial age estimation or ID document verification (Didit) — your app only passes country. Your server calls it twice with an API key and gets back only whether the user is an adult and a value that identifies the same person within your app.

• Name, phone number, gender, raw CI/DI, full date of birth, document number and face images are never sent to your app, and CP does not store them.
• Do not call it from the browser. Keep the API key on your server.

Permissions

• Your app must have the identity service enabled.
• The API key needs the identity.verify permission (identity.* also works). pay.* does not grant it.
• After enabling the service, issue a new key. Existing keys keep their original permissions.

Test and live modes

The mode is live only when the key is live and the service is approved for live identity verification. Everything else is test. Identity live approval is separate from payment live approval (a service whose payments are still in test can be approved for live identity only); a service approved for live payments is also live for identity.

Overseas requests (country other than KR) go to the Didit sandbox in test mode. Do not send sandbox parameters for them — if you do, the request goes to the deterministic sandbox above regardless of country. Pick the outcome (approved, in review, declined) with "Select test result" on the Didit screen; the selfie step needs a real camera.

Check availability

You don't need to create a session to decide whether to turn your gate on. This tells you, without creating anything, whether this key can complete a verification right now.

GET /identity/availability?country=AU
X-API-Key: <key with identity.verify>

Pass country (ISO-3166 alpha-2, optional) to get the answer for users in that country. Without it the answer is for Korea.

{ "mode": "live", "provider": "portone", "sandbox": false, "available": false }

With available: false, creating or confirming a verification ends in 503 IDENTITY_NOT_CONFIGURED. Keep your existing age check until it turns true, then switch to the verification gate. In production, don't treat sandbox: true as available.

1. Create a verification

{
  "userRef": "user_123",
  "successUrl": "https://your-app.example/identity/done",
  "failUrl": "https://your-app.example/identity/failed",
  "sandbox": { "birthday": "20080101", "personKey": "tester-a", "outcome": "success" }
}

{
  "verificationId": "7f0c…",
  "mode": "live",
  "provider": "toss_cert",
  "sandbox": false,
  "txId": "c1ce9214-…",
  "authUrl": "https://auth.cert.toss.im/start?serviceType=SIGN_USER_AUTH",
  "sdk": { "scriptUrl": "https://cdn.toss.im/cert/v1", "call": "tossCert.start({ authUrl, txId, onSuccess, onFail })" },
  "expiresAt": "2026-09-24T04:00:00+00:00"
}

The client opens the Toss standard window with authUrl and txId.

<script src="https://cdn.toss.im/cert/v1"></script>
<script>
  tossCert.start({
    authUrl, txId,
    onSuccess: () => fetch("/api/identity/confirm", { method: "POST", body: JSON.stringify({ verificationId, txId }) }),
    onFail: (e) => console.warn(e),
  });
</script>

In test mode authUrl is successUrl?txId=…&verificationId=…. Sending the user there simulates a completed verification.

When provider is "portone"

authUrl is null; pass sdk.params as is to the PortOne browser SDK. storeId and channelKey are public values and safe in the browser (the secret stays on CP servers). identityVerificationId is generated by CP and equals txId — do not create your own on the client.

{
  "verificationId": "7f0c…",
  "provider": "portone",
  "txId": "cpiv3f9a…",
  "authUrl": null,
  "sdk": {
    "scriptUrl": "https://cdn.portone.io/v2/browser-sdk.js",
    "call": "PortOne.requestIdentityVerification(params)",
    "params": { "storeId": "store-…", "identityVerificationId": "cpiv3f9a…", "channelKey": "channel-key-…", "redirectUrl": "https://your-app.example/identity/done" }
  }
}

<script src="https://cdn.portone.io/v2/browser-sdk.js"></script>
<script type="module">
  const res = await PortOne.requestIdentityVerification(sdk.params);
  if (res.code !== undefined) throw new Error(res.message); // canceled / failed
  // The verdict is server-side only: your server calls the CP confirm API (the SDK response is not trusted)
  await fetch("/api/identity/confirm", { method: "POST", body: JSON.stringify({ verificationId, txId }) });
</script>

On mobile web the user returns to redirectUrl (= successUrl); confirm the same way. On desktop the KCP window opens as a popup, so call requestIdentityVerification when the user clicks a button (calling it automatically gets the popup blocked and fails right away).

Users outside Korea (country ≠ KR) — provider: "didit"

Verification outside Korea is not open yet. A country other than KR returns 400 COUNTRY_NOT_SUPPORTED, and the availability check (?country=) reports available: false. The steps below apply once it opens.

Add country to the create request. Without it, or with KR, the Korean flow above is unchanged.

{ "userRef": "user_123", "country": "AU", "successUrl": "https://your-app.example/identity/done" }

The method is fixed per country.

The response authUrl is the Didit screen and sdk is null. Send the user there (or open it in a web view). They come back to successUrl, and you confirm on your server exactly as for Korea.

{ "verificationId": "3895…", "mode": "live", "provider": "didit", "method": "AGE_ESTIMATION", "country": "AU",
  "txId": "cpdi…", "authUrl": "https://verify.didit.me/session/…", "sdk": null, "expiresAt": "…" }

• On a desktop browser the screen shows a QR code and the user continues on their phone (a camera is required). Tell users this on your screen.
• Don't ask users to type a two-letter code for their country — use a country picker with localized names, prefilled from location or sign-up country.
• ★Decide the country on your server (location, sign-up country, store region) so users in Korea cannot pick another country to skip the mobile identity check. The country in the confirm response just echoes what you sent — it is not a verified country of residence.

2. Confirm the result

{ "txId": "c1ce9214-…", "userRef": "user_123" }

userRef is optional but recommended. When sent, it must match the user the verification was created for, otherwise 403 USER_REF_MISMATCH (blocks confirming another user's session).

{
  "verificationId": "7f0c…",
  "status": "verified",
  "verified": true,
  "isAdult": true,
  "birthYear": 2001,
  "ciHash": "9b1e…(64 hex chars)",
  "verifiedAt": "2026-09-24T03:05:12+00:00",
  "mode": "live",
  "sandbox": false,
  "userRef": "user_123"
}

• Confirm is idempotent. A settled verification returns the same result again.
• GET /identity/verifications/{verificationId} reads the stored result.
• On failure you get verified: false, status: "failed" and a failureCode.

The confirm response also carries these fields (existing fields keep their names and meaning).

Age estimation results have no birth year (birthYear: null). Because face estimates have an error margin, isAdult is true only for an estimate of 25 or more. Below 25 you get status: "failed", failureCode: "AGE_ESTIMATE_BELOW_THRESHOLD" and nextStep: "DOCUMENT". Document results are decided from the date of birth, so birthYear is present.

How isAdult is decided

It is true from the day the user completes 19 full years (Korea time; people born on 29 February turn a year older on 1 March in non-leap years). Korea's Juvenile Protection Act also treats people who have reached 1 January of the year they turn 19 as adults, so the legal rule is slightly wider. This API takes the stricter side. If you need the calendar-year rule, check birthYear <= currentYear - 19 yourself.

ciHash

For overseas verifications the same field holds a face-based (FACE) or document-based (DOC) value. Values of different kinds differ even for the same person.

An HMAC of the CI with a key that differs per app. Within one app the same person always gets the same value, so you can block duplicate or multiple accounts. Across apps the values differ, so apps cannot link people to each other, and the value cannot be turned back into the CI.

Errors

Error bodies look like {"detail": {"code", "message"}}.

Retention

CP keeps only the app ID, userRef, result, birth year, ciHash (personKey), method, country, estimated age (whole years) and timestamps. Full dates of birth, document numbers and face images from overseas checks are not kept. Unfinished records are deleted after 30 days and verified records after one year.