Verifying customers (KYC)

You never handle your customer’s identity documents. You ask for a link, send them the link, and a signed webhook tells you the outcome.

Create an application

POST /api/v1/kyc/applications returns a link_url valid for a limited time.

Send the link to your customer

SMS, email, in-app — your channel. Nothing else is required of you.

They complete it on their phone

They photograph their ID and record a short video. Those images go straight to the verification service; they never pass through your integration.

You receive the verdict

A KYC_COMPLETED, KYC_REJECTED, KYC_NEEDS_REVIEW, KYC_FAILED or KYC_EXPIRED webhook at the endpoints you already registered.

This API is asynchronous end to end. Creating an application returns as soon as a link exists — long before your customer has done anything with it. There is no synchronous variant: a verification takes as long as the applicant takes, which is unbounded.

Create an application

curl -X POST http://localhost:8080/api/v1/kyc/applications \
  -H "X-API-Key: sk_live_…" -H 'Content-Type: application/json' \
  -d '{
    "external_id": "cust_8842",
    "locale": "fr",
    "redirect_url": "https://yourapp.dz/onboarding/done",
    "metadata": { "signup_id": "S-1042" }
  }'

{
  "id": "9f1c…",
  "status": "CREATED",
  "external_id": "cust_8842",
  "link_url": "https://kyc.dinari.dz/s/vs_7f3a…",
  "link_expires_at": "2026-08-11T12:00:00Z",
  "created_at": "2026-08-08T12:00:00Z"
}

Treat link_url as a secret. Anyone holding it can submit identity documents against this application. Send it over a channel you would send a password reset over — and do not log it, put it in an analytics event, or embed it in a shareable page.

Options worth knowing

Field	Default	Notes
`external_id`	—	Your own id for this applicant. Echoed on every webhook, so you never store ours.
`locale`	`fr`	`fr`, `ar` or `en`. The capture page renders right-to-left for Arabic.
`allowed_documents`	both	Restrict to `["id_card"]` or `["passport"]`.
`require_video`	`true`	See the warning below before turning this off.
`redirect_url`	—	Where the applicant lands when they finish.
`profile`	—	What the applicant told you (`first_name`, `last_name`, `birth_date`, …). Cross-checked against the document; a mismatch is a review reason.
`metadata`	`{}`	Opaque object, echoed back untouched.
`ttl_hours`	72	Link lifetime.
`max_attempts`	3	How many times they may re-submit on this link.
`client_id`	—	Link to an existing Dinari customer, if there is one.

Leave require_video on. A single still photograph cannot establish that a live person is present — one frame is indistinguishable from a photograph of a photograph. An application with it turned off can never be auto-approved and will always land in manual review, which is slower for everyone. Turn it off only for a flow where a human confirms the holder some other way.

Handling the result

The webhook arrives at the endpoints you registered under Webhooks — the same signed, retrying channel your payment events use.

{
  "event": "KYC_NEEDS_REVIEW",
  "application_id": "9f1c…",
  "business_id": "…",
  "external_id": "cust_8842",
  "client_id": null,
  "status": "COMPLETED",
  "verdict": "NEEDS_REVIEW",
  "decision_summary": "Possible sanctions match requires review.",
  "reason_codes": ["aml_possible_match"],
  "needs_review": true,
  "metadata": { "signup_id": "S-1042" },
  "occurred_at": "2026-08-08T12:04:11Z"
}

Event	What to do
`KYC_COMPLETED`	Verified. Safe to onboard.
`KYC_REJECTED`	The check failed. `reason_codes` says why.
`KYC_NEEDS_REVIEW`	Wait. See below.
`KYC_FAILED`	The pipeline failed, not your customer. They can retry on the same link if attempts remain.
`KYC_EXPIRED`	The link lapsed unused. Create a new application.
`KYC_REVIEW_RESOLVED`	A compliance officer decided a previously-pending case. Read `verdict`.

KYC_NEEDS_REVIEW is not a soft approval. A possible sanctions match is never cleared automatically — a human has to look at it. Do not onboard the customer, and do not treat the absence of a rejection as a yes. You will receive KYC_REVIEW_RESOLVED when the decision is made, usually within a working day.

Reading applications back

# One application
curl -H "X-API-Key: sk_live_…" http://localhost:8080/api/v1/kyc/applications/9f1c…

# Everything still in flight
curl -H "X-API-Key: sk_live_…" \
  "http://localhost:8080/api/v1/kyc/applications?status=PROCESSING&page_size=50"

# By your own identifier
curl -H "X-API-Key: sk_live_…" \
  "http://localhost:8080/api/v1/kyc/applications?external_id=cust_8842"

Polling is a fallback, not the design — use the webhook. synced_at on each row tells you when Dinari last heard from the verification service about it, which is the field to look at if you suspect a callback went missing.

What we do and do not hold

The response tells you the decision, the reason codes and non-identifying document facts (type, expiry, nationality). It does not return your customer’s name, document number or images, and neither does the webhook. That is not an omission — Dinari does not store them. They stay inside the verification service and are released only to an authorised compliance operator looking at a specific case. If your own regulator requires you to hold identity documents, collect them under your own obligation; this API is not that channel.

Cancelling a link

curl -X POST http://localhost:8080/api/v1/kyc/applications/9f1c…/cancel \
  -H "X-API-Key: sk_live_…"

The link stops working immediately and the applicant sees an explanation rather than a dead page. Cancelling one that already completed, expired or was cancelled returns 409 — there is nothing left to revoke.

When KYC is not enabled

If this deployment has no verification service configured, every endpoint here answers 503 with {"error": "kyc_unavailable"}. Payments and the rest of the API are unaffected — the feature is optional, and its absence does not take the platform down.

Get Started

Concepts

Guides

Reference

Verifying customers (KYC)

Create an application

Options worth knowing

Handling the result

Reading applications back

What we do and do not hold

Cancelling a link

When KYC is not enabled

​Create an application

​Options worth knowing

​Handling the result

​Reading applications back

​What we do and do not hold

​Cancelling a link

​When KYC is not enabled

Create an application

Options worth knowing

Handling the result

Reading applications back

What we do and do not hold

Cancelling a link

When KYC is not enabled