Upgrade a Team's KYC tier

POST

/api/v2/account_kycs/upgrade

const url = 'https://auth.payhero.africa/api/v2/account_kycs/upgrade';
const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <credentials>', 'Content-Type': 'application/json'},
  body: '{"account_id":63,"upgrade_information":{"upgrade_to":3,"upgrade_notes":"Adding third-party collections"},"kyc_tokens":{"national_id":"9f2c61ab4d7e4a0c8b115d3e","tin":"a1b2c3d4e5f6a7b8c9d0e1f2"}}'
};

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/upgrade \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "account_id": 63, "upgrade_information": { "upgrade_to": 3, "upgrade_notes": "Adding third-party collections" }, "kyc_tokens": { "national_id": "9f2c61ab4d7e4a0c8b115d3e", "tin": "a1b2c3d4e5f6a7b8c9d0e1f2" } }'

Raises an already-approved Team to a higher tier. Attach kyc_tokens covering the requested tier and the upgrade is granted immediately; otherwise it is recorded as pending for review.

Tokens top out at tier 3 — a tier 4 request, or tier 3 backed only by an individual taxpayer, always goes to a reviewer.

Authorizations

basicAuth

Request Body^required

application/json

object

account_id

required

integer

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

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

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

Upgrade to tier 3 with tokens

{
  "account_id": 63,
  "upgrade_information": {
    "upgrade_to": 3,
    "upgrade_notes": "Adding third-party collections"
  },
  "kyc_tokens": {
    "national_id": "9f2c61ab4d7e4a0c8b115d3e",
    "tin": "a1b2c3d4e5f6a7b8c9d0e1f2"
  }
}

Responses

200

The updated KYC record.

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
}

Upgrade a Team's KYC tier

Authorizations

Request Bodyrequired

Examples

Responses

200

Example

400

Examples

401

Example

Request Body^required