Starting a Verification

Create it

POST /api/v1/verifications with a bearer token holding transactions:write. An online request is method: "eid" without an identifier.

curl -X POST https://<our-host>/api/v1/verifications \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: order-1001-check" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "eid",
    "requiredAge": 18,
    "externalReference": "order-1001",
    "returnUrl": "https://<shop>.myshopify.com/pages/age-check"
  }'

Idempotency-Key is optional and works as in eID Verification. A replay returns the stored answer with Idempotent-Replayed: true, including the same link even after it has expired; start a new Verification with a new key to get a fresh one.

Answer, 200:

{
  "id": "<verification-id>",
  "status": "pending",
  "verifyUrl": "https://<our-host>/verify/<shopper-token>",
  "expiresAt": 1767225600000,
  "livemode": true
}

Send the shopper to verifyUrl (it expires after 30 minutes). Keep id: it is the Verification's id.

Read the outcome

GET /api/v1/verifications/{id}. You can only read the Verifications your shop started; any other id is 404. Prefer the result callback and use this to confirm it, or when no callback comes.

{
  "id": "<verification-id>",
  "status": "success",
  "result": "pass",
  "transactionId": "<transaction-id>",
  "externalReference": "order-1001",
  "livemode": true
}

externalReference is the one you sent at start. Match the Verification to your order by it, or by the id you stored when you started it, never by the abyrg_verification parameter on the shopper's return URL: that comes through the shopper's browser and can be changed.

A Verification still pending after expiresAt is closed when you read it. If the shopper never started eID it reads timeout and no callback is sent. If they confirmed in the eID app but their tab stayed closed, this read asks the eID Provider once and records the outcome: one Transaction and one result callback, the same as if the shopper's page had finished it. If the eID Provider has not answered yet, the Verification stays pending and the next read asks again; once about 15 minutes have passed since expiresAt with no answer, it reads timeout (no Transaction, no callback). So a shop that never gets a callback should read the Verification once its expiresAt has passed.

Errors: 400 for a body that breaks the rules above, 401 without a valid token, 403 without transactions:write, 404 for an id that isn't yours, 429 when rate limited. All are Problem Details; see Errors.