Submit KYC for a Team

POST

/api/v2/account_kycs

const url = 'https://auth.payhero.africa/api/v2/account_kycs';
const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <credentials>', 'Content-Type': 'application/json'},
  body: '{"account_id":63,"entity_type":"business","country_code":"KE","country":"Kenya","kyc_tier":3,"contact_information":{"first_name":"Jane","last_name":"Doe","identification_number":12345678,"identification_type":"national_id","phone_number":"+254712345678","upload_information":{"identification_front_document":"https://cdn.acme.co/kyc/id-front.jpg","identification_back_document":"https://cdn.acme.co/kyc/id-back.jpg","selfie_image":"https://cdn.acme.co/kyc/selfie.jpg"}},"entity_information":{"entity_name":"Vendor A Ltd","nature_of_business":"Internet Service Provider","business_type":"limited_company","entity_address":"Westlands, Nairobi"},"account_information":{"currency":"KES","organization_id":"9","account_name":"Vendor A","email":"vendor-a@acme.co","phone_number":"+254711000111"}}'
};

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

curl --request POST \
  --url https://auth.payhero.africa/api/v2/account_kycs \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "account_id": 63, "entity_type": "business", "country_code": "KE", "country": "Kenya", "kyc_tier": 3, "contact_information": { "first_name": "Jane", "last_name": "Doe", "identification_number": 12345678, "identification_type": "national_id", "phone_number": "+254712345678", "upload_information": { "identification_front_document": "https://cdn.acme.co/kyc/id-front.jpg", "identification_back_document": "https://cdn.acme.co/kyc/id-back.jpg", "selfie_image": "https://cdn.acme.co/kyc/selfie.jpg" } }, "entity_information": { "entity_name": "Vendor A Ltd", "nature_of_business": "Internet Service Provider", "business_type": "limited_company", "entity_address": "Westlands, Nairobi" }, "account_information": { "currency": "KES", "organization_id": "9", "account_name": "Vendor A", "email": "vendor-a@acme.co", "phone_number": "+254711000111" } }'

Attaches identity and (for businesses) entity information to a Team.

Without kyc_tokens, the submission returns status: "pending" and PayHero reviews it asynchronously. With verified kyc_tokens, it is approved on submission at the tier the tokens justify, and the Team moves to that tier immediately.

See Verification tokens and KYC tiers & limits.

Authorizations

basicAuth

Request Body^required

application/json

object

account_id

required

integer

entity_type

individual or business.

string

country_code

string

country

string

kyc_tier

integer

notes

string

contact_information

object

first_name

string

last_name

string

surname

string

entity_type

string

identification_number

integer

identification_type

string

secondary_identification_number

integer

secondary_identification_type

string

status

string

phone_number

string

upload_information

References to uploaded KYC document files.

object

identification_front_document

string

identification_back_document

string

secondary_identification_front_document

string

secondary_identification_back_document

string

selfie_image

string

tax_document

string

proof_of_address_document

string

entity_certificate_document

string

entity_shareholding_document

string

entity_information

object

entity_name

string

entity_directors

string

nature_of_business

string

business_type

string

entity_address

string

tax_document_number

integer

entity_certificate_number

integer

upload_information

References to uploaded KYC document files.

object

identification_front_document

string

identification_back_document

string

secondary_identification_front_document

string

secondary_identification_back_document

string

selfie_image

string

tax_document

string

proof_of_address_document

string

entity_certificate_document

string

entity_shareholding_document

string

account_information

object

currency

string

organization_id

string

account_name

string

email

string

phone_number

string

kyc_status

string

account_status

string

is_phone_verified

boolean

is_email_verified

boolean

kyc_tokens

Verification tokens backing a KYC submission. Each value is a lookup_id returned by a check. All slots are optional; PayHero resolves every token against Axxa Connect and rejects one it never issued.

object

national_id

A token from a national_id_* or nin check.

string

phone_number

A token from a phone or phone_status_global check.

string

tin

A token from a kra_pin or tin_global check.

string

Examples

{
  "account_id": 63,
  "entity_type": "business",
  "country_code": "KE",
  "country": "Kenya",
  "kyc_tier": 3,
  "contact_information": {
    "first_name": "Jane",
    "last_name": "Doe",
    "identification_number": 12345678,
    "identification_type": "national_id",
    "phone_number": "+254712345678",
    "upload_information": {
      "identification_front_document": "https://cdn.acme.co/kyc/id-front.jpg",
      "identification_back_document": "https://cdn.acme.co/kyc/id-back.jpg",
      "selfie_image": "https://cdn.acme.co/kyc/selfie.jpg"
    }
  },
  "entity_information": {
    "entity_name": "Vendor A Ltd",
    "nature_of_business": "Internet Service Provider",
    "business_type": "limited_company",
    "entity_address": "Westlands, Nairobi"
  },
  "account_information": {
    "currency": "KES",
    "organization_id": "9",
    "account_name": "Vendor A",
    "email": "vendor-a@acme.co",
    "phone_number": "+254711000111"
  }
}

Approved on submission — no reviewer

A national ID plus a company KRA PIN reaches tier 3. The response comes back status: "approved" with kyc_tier: 3.

{
  "account_id": 63,
  "entity_type": "business",
  "country_code": "KE",
  "country": "Kenya",
  "contact_information": {
    "first_name": "Jane",
    "last_name": "Doe",
    "identification_number": 12345678,
    "identification_type": "national_id",
    "phone_number": "+254712345678"
  },
  "entity_information": {
    "entity_name": "Vendor A Ltd",
    "nature_of_business": "Internet Service Provider",
    "business_type": "limited_company"
  },
  "kyc_tokens": {
    "national_id": "9f2c61ab4d7e4a0c8b115d3e",
    "phone_number": "c41e77d9b0a24f6e89305ab2",
    "tin": "a1b2c3d4e5f6a7b8c9d0e1f2"
  }
}

Responses

200

The KYC submission.

application/json

object

account_kyc

object

integer

account_id

integer

entity_type

string

status

string

country_code

string

country

string

kyc_tier

integer

notes

string

contact_information

object

first_name

string

last_name

string

surname

string

entity_type

string

identification_number

integer

identification_type

string

secondary_identification_number

integer

secondary_identification_type

string

status

string

phone_number

string

upload_information

References to uploaded KYC document files.

object

identification_front_document

string

identification_back_document

string

secondary_identification_front_document

string

secondary_identification_back_document

string

selfie_image

string

tax_document

string

proof_of_address_document

string

entity_certificate_document

string

entity_shareholding_document

string

entity_information

object

entity_name

string

entity_directors

string

nature_of_business

string

business_type

string

entity_address

string

tax_document_number

integer

entity_certificate_number

integer

upload_information

References to uploaded KYC document files.

object

identification_front_document

string

identification_back_document

string

secondary_identification_front_document

string

secondary_identification_back_document

string

selfie_image

string

tax_document

string

proof_of_address_document

string

entity_certificate_document

string

entity_shareholding_document

string

account_information

object

currency

string

organization_id

string

account_name

string

email

string

phone_number

string

kyc_status

string

account_status

string

is_phone_verified

boolean

is_email_verified

boolean

upgrade_information

object

requested_kyc_upgrade

boolean

upgrade_from

integer

upgrade_to

integer

upgrade_notes

string

upgrade_status

string

upgrade_requested_at

string format: date-time

upgrade_reviewed_at

string format: date-time

upgrade_reviewed_by

The reviewer’s user id. Absent when the tokens settled it without review.

integer

verification_information

The record of what the submitted tokens proved. Kept on the KYC submission so the basis for a tier stays auditable.

object

kyc_tokens

object

national_id

A token from a national_id_* or nin check.

string

phone_number

A token from a phone or phone_status_global check.

string

tin

A token from a kra_pin or tin_global check.

string

verifications

Array<object>

One resolved token, recorded on the KYC submission.

object

kind

The slot it was submitted in.

string

Allowed values: national_id phone_number tin

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

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

string

reference

string

source

string

verified_at

string format: date-time

expires_at

string format: date-time

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

verified_kyc_tier

The tier the tokens justify on their own.

integer

verified_at

string format: date-time

created_at

string format: date-time

updated_at

string format: date-time

Example

{
  "account_kyc": {
    "id": 501,
    "account_id": 63,
    "entity_type": "business",
    "status": "pending",
    "country_code": "KE",
    "country": "Kenya",
    "kyc_tier": 3,
    "contact_information": {
      "first_name": "Jane",
      "last_name": "Doe",
      "identification_number": 12345678,
      "identification_type": "national_id",
      "phone_number": "+254712345678"
    },
    "entity_information": {
      "entity_name": "Vendor A Ltd",
      "nature_of_business": "Internet Service Provider",
      "business_type": "limited_company",
      "entity_address": "Westlands"
    },
    "account_information": {
      "currency": "KES",
      "organization_id": "9",
      "account_name": "Vendor A",
      "email": "vendor-a@acme.co",
      "phone_number": "+254711000111"
    },
    "upgrade_information": {
      "requested_kyc_upgrade": true,
      "upgrade_from": 2,
      "upgrade_to": 3,
      "upgrade_notes": "Adding third-party collections",
      "upgrade_status": "approved"
    },
    "verification_information": {
      "kyc_tokens": {
        "national_id": "9f2c61ab4d7e4a0c8b115d3e",
        "phone_number": "c41e77d9b0a24f6e89305ab2",
        "tin": "a1b2c3d4e5f6a7b8c9d0e1f2"
      },
      "verifications": [
        {
          "kind": "national_id",
          "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"
        }
      ],
      "actor_type": "C",
      "verified_kyc_tier": 3
    }
  }
}

400

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

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

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
}

Submit KYC for a Team

Authorizations

Request Bodyrequired

Examples

Responses

200

Example

400

Examples

401

Example

Request Body^required