Start verification for a customer

curl --request POST \
  --url https://api.paystack.com/v1/customers/{customerId}/verifications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "redirect_url": "<string>"
}
'

{
  "status": true,
  "message": "Verification session created",
  "code": "ok",
  "data": {
    "id": "kyc_01HXYZABC1234567890ABCDEFG",
    "customer_id": "cust_01HXYZABC1234567890ABCDEFG",
    "status": "pending",
    "tier_requested": "tier_1",
    "tier_current": "tier_0",
    "hosted_url": "http://localhost:3000/_mock/verify/kyc_01HXYZABC1234567890ABCDEFG",
    "hosted_url_expires_at": "2026-04-22T03:00:00.000Z",
    "created_at": "2026-04-22T02:00:00.000Z",
    "updated_at": "2026-04-22T02:00:00.000Z"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Customers

Start verification for a customer

Creates a hosted verification session for a customer scoped to the calling integration. The returned hosted_url is the hosted verification link that the merchant must surface to their customer to complete verification.

Path

customer_id — required. The cust_… external id of an existing, non-default customer that belongs to the calling integration.

Body

tier — optional. One of tier_1, tier_2. Defaults to the next tier above the customer’s current tier (tier_0 → tier_1; tier_1 → tier_2). tier_0 is never a valid requested tier.
redirect_url — optional. HTTPS URL the merchant wants the customer redirected to after the verification flow completes. Stored verbatim and echoed back on the response.

Replay & link refresh

If a pending session already exists for the same (customer_id, tier_requested) and its hosted_url_expires_at is in the future, this endpoint returns that existing session unchanged — no second upstream call. Clients can safely retry POSTs without an Idempotency-Key header.

If that pending session exists but its hosted_url has expired, this endpoint mints a fresh hosted link and refreshes the same session in place, returning it with a new hosted_url / hosted_url_expires_at. Call this endpoint again to regenerate an expired verification link.

Example

POST /v1/customers/cust_01HXYZ/verifications
{
  "tier": "tier_1",
  "redirect_url": "https://merchant.com/onboarding/complete"
}

POST

customers

{customerId}

verifications

Start verification for a customer

curl --request POST \
  --url https://api.paystack.com/v1/customers/{customerId}/verifications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "redirect_url": "<string>"
}
'

{
  "status": true,
  "message": "Verification session created",
  "code": "ok",
  "data": {
    "id": "kyc_01HXYZABC1234567890ABCDEFG",
    "customer_id": "cust_01HXYZABC1234567890ABCDEFG",
    "status": "pending",
    "tier_requested": "tier_1",
    "tier_current": "tier_0",
    "hosted_url": "http://localhost:3000/_mock/verify/kyc_01HXYZABC1234567890ABCDEFG",
    "hosted_url_expires_at": "2026-04-22T03:00:00.000Z",
    "created_at": "2026-04-22T02:00:00.000Z",
    "updated_at": "2026-04-22T02:00:00.000Z"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Authorizations

Authorization

string

header

required

API key issued during merchant onboarding.

Headers

Idempotency-Key

string

Optional client-supplied key. Identical key + identical body within 24h replays the original response. Identical key + different body returns 409 idempotency_conflict. The hash is over raw bytes — clients retrying must send the byte-identical body; a re-serialised JSON payload will produce a different hash and a 409. Strongly recommended for retry-safe clients.

Pattern: ^[A-Za-z0-9_\-]{8,255}$

Body

application/json

CreateVerifyDto

tier

enum<string>

Available options:

tier_0,

tier_1,

tier_2

redirect_url

string<url>

Maximum string length: 2048

Response

Verification session created

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Verification session created"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object

required

Show child attributes