Run a verification check

POST

/api/v1/kyc/verify/{check}

curl --request POST \
  --url 'https://connect.payhero.africa/api/v1/kyc/verify/kra_pin?fresh=true' \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "number": "P000000000X" }'

• Axxa Connect (verification)

Runs one identity, business, phone or bank account check and returns a lookup_id — the verification token.

The request body is a flat object of string fields; which fields are required depends on the check. Call GET /api/v1/kyc/checks for the catalogue.

A check that ran but found no match returns 200 with status: "not_verified" — always read status, never treat 200 as proof.

Authorizations

• basicAuth

Parameters

Path Parameters

check

required

string

The check key, e.g. kra_pin, national_id_ke, phone, bank_account_ke.

Example

kra_pin

Query Parameters

fresh

boolean

Set to true to bypass the cache and force a live provider call.

Example

true

Request Body^required

Media typeapplication/json

object

key

additional properties

string

Examples

Business tax PIN

{
  "number": "P000000000X"
}

{
  "number": "28200002"
}

{
  "number": "254712345678"
}

{
  "account_no": "2096844395",
  "bank_id": "34"
}

{
  "number": "0123456789",
  "bank_code": "058"
}

{
  "tin": "MWI789456123",
  "country": "MW"
}

{
  "company_number": "PVT-ABCDEFG",
  "country_code": "KE"
}

Responses

200

The check result. Read status for the verdict.

Media typeapplication/json

The outcome of one check. Identical in shape whichever check ran.

object

lookup_id

The verification token. Attach it to a KYC submission or resolve it later.

string

check

string

category

The kind of check, independent of which provider ran it. Decides what a token is worth when attached to a Team’s KYC.

string

Allowed values: national_id tax_id phone passport bank_account bank_id company

country

The country the check actually ran against — the input country for global checks.

string

status

verified — the identifier was confirmed. not_verified — the check ran and found no match. error — the check could not be completed.

string

Allowed values: verified not_verified error

verification_status

The provider’s own verdict.

string

actor_type

C for a company, I for a natural person. Absent when the check cannot tell. Only tax_id and company checks can distinguish; an ID card or a phone line always reports I.

string

Allowed values: C I

subject_name

The registered name, normalised out of the provider payload.

string

reference

string

detail

string

response_code

string

data

The raw provider payload. Shape varies per check, per country and occasionally per record — read subject_name and actor_type instead of reaching into this.

object

key

additional properties

any

duration_ms

integer

source

prembly for a live call, cache for a replay.

string

Allowed values: prembly cache

cached

boolean

fetched_at

string format: date-time

expires_at

When the cached result lapses.

string format: date-time

charged_amount

What this call cost. 0 on your own provider key.

number

charge_currency

string

charge_reference

string

charge_status

string

Allowed values: charged refunded refund_failed free

Example

{
  "lookup_id": "a1b2c3d4e5f6a7b8c9d0e1f2",
  "check": "kra_pin",
  "category": "national_id",
  "country": "KE",
  "status": "verified",
  "verification_status": "VERIFIED",
  "actor_type": "C",
  "subject_name": "ACME TRADING LIMITED",
  "reference": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "detail": "KRA PIN Checker (Kenya) verification successful",
  "response_code": "00",
  "duration_ms": 412,
  "source": "prembly",
  "cached": true,
  "charged_amount": 20,
  "charge_currency": "KES",
  "charge_reference": "cmp_a1b2c3d4e5f6a7b8c9d0e1f2",
  "charge_status": "charged"
}

400

The request was rejected (validation or business-rule failure).

Media typeapplication/json

object

error_code

string

error_message

string

status_code

integer

Examples

{
  "error_code": "invalid_argument",
  "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)",
  "status_code": 400
}

{
  "error_code": "invalid_argument",
  "error_message": "The passed channel is not active",
  "status_code": 400
}

401

Missing or invalid Basic auth credentials.

Media typeapplication/json

object

error_code

string

error_message

string

status_code

integer

Example

{
  "error_code": "invalid_argument",
  "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)",
  "status_code": 400
}

402

The Team’s service wallet cannot cover the check.

Media typeapplication/json

object

error

string

reason

Machine-readable cause, on billing and entitlement failures.

string

Example

{
  "error": "insufficient service wallet balance",
  "reason": "insufficient_balance"
}

403

Identity checks are not available on this PayHero account.

Media typeapplication/json

object

error

string

reason

Machine-readable cause, on billing and entitlement failures.

string

Example

{
  "error": "insufficient service wallet balance",
  "reason": "insufficient_balance"
}

404

Unknown check key.

412

Identity checks are not enabled — connect a provider key first.

Media typeapplication/json

object

error

string

reason

Machine-readable cause, on billing and entitlement failures.

string

Example

{
  "error": "insufficient service wallet balance",
  "reason": "insufficient_balance"
}

502

The identity provider or billing was unreachable. Safe to retry.

Media typeapplication/json

object

error

string

reason

Machine-readable cause, on billing and entitlement failures.

string

Example

{
  "error": "insufficient service wallet balance",
  "reason": "insufficient_balance"
}