Resolve a verification token

GET

/api/v1/kyc/tokens/{token}

const url = 'https://connect.payhero.africa/api/v1/kyc/tokens/a1b2c3d4e5f6a7b8c9d0e1f2';
const options = {method: 'GET', headers: {Authorization: 'Basic <credentials>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://connect.payhero.africa/api/v1/kyc/tokens/a1b2c3d4e5f6a7b8c9d0e1f2 \
  --header 'Authorization: Basic <credentials>'

Reads back what an earlier check proved. A token belonging to another merchant returns 404, exactly as an unknown token does — the API never confirms that someone else’s token exists.

Authorizations

basicAuth

Parameters

Path Parameters

token

required

string

The lookup_id returned by a check.

Example

a1b2c3d4e5f6a7b8c9d0e1f2

Query Parameters

data

boolean

Set to true to include the raw provider payload, withheld by default.

Responses

200

What the token proved.

application/json

A resolved verification token — what an earlier check proved.

object

token

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

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

string

verified

Shorthand for status == "verified". Read this.

boolean

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

string

identifier_masked

The identifier that was checked, masked. Never stored in the clear.

string

reference

string

detail

string

source

string

account_id

integer

data

The raw provider payload. Only present when ?data=true was sent.

object

key

additional properties

any

verified_at

When the check ran.

string format: date-time

expires_at

When the underlying cached result lapses. The token stays resolvable after this.

string format: date-time

Example

{
  "token": "a1b2c3d4e5f6a7b8c9d0e1f2",
  "check": "kra_pin",
  "category": "national_id",
  "country": "KE",
  "status": "verified",
  "verification_status": "VERIFIED",
  "verified": true,
  "actor_type": "C",
  "subject_name": "ACME TRADING LIMITED",
  "identifier_masked": "P00•••••00X",
  "source": "cache",
  "account_id": 63
}

401

Missing or invalid Basic auth credentials.

application/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
}

404

Unknown token, or a token belonging to another merchant.