Update a Team's KYC

PUT

/api/v2/account_kycs/{id}

curl --request PUT \
  --url https://auth.payhero.africa/api/v2/account_kycs/501 \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "account_id": 63, "entity_type": "business", "country_code": "KE", "country": "Kenya", "kyc_tier": 3, "notes": "example", "contact_information": { "first_name": "Jane", "last_name": "Doe", "surname": "example", "entity_type": "example", "identification_number": 12345678, "identification_type": "national_id", "secondary_identification_number": 1, "secondary_identification_type": "example", "status": "example", "phone_number": "+254712345678", "upload_information": { "identification_front_document": "example", "identification_back_document": "example", "secondary_identification_front_document": "example", "secondary_identification_back_document": "example", "selfie_image": "example", "tax_document": "example", "proof_of_address_document": "example", "entity_certificate_document": "example", "entity_shareholding_document": "example" } }, "entity_information": { "entity_name": "Vendor A Ltd", "entity_directors": "example", "nature_of_business": "Internet Service Provider", "business_type": "limited_company", "entity_address": "Westlands", "tax_document_number": 1, "entity_certificate_number": 1, "upload_information": { "identification_front_document": "example", "identification_back_document": "example", "secondary_identification_front_document": "example", "secondary_identification_back_document": "example", "selfie_image": "example", "tax_document": "example", "proof_of_address_document": "example", "entity_certificate_document": "example", "entity_shareholding_document": "example" } }, "account_information": { "currency": "KES", "organization_id": "9", "account_name": "Vendor A", "email": "vendor-a@acme.co", "phone_number": "+254711000111", "kyc_status": "example", "account_status": "example", "is_phone_verified": true, "is_email_verified": true }, "kyc_tokens": { "national_id": "9f2c61ab4d7e4a0c8b115d3e", "phone_number": "c41e77d9b0a24f6e89305ab2", "tin": "a1b2c3d4e5f6a7b8c9d0e1f2" } }'

• PayHero Africa auth API (Teams)

Amends a KYC submission (e.g. attach a missing document). Accepts the same fields as Submit.

Authorizations

• basicAuth

Parameters

Path Parameters

id

required

integer

Example

501

Request Body^required

Media typeapplication/json

object

account_id

required

integer

Example

63

entity_type

individual or business.

string

Example

business

country_code

string

Example

KE

country

string

Example

Kenya

kyc_tier

integer

Example

3

notes

string

contact_information

object

first_name

string

Example

Jane

last_name

string

Example

Doe

surname

string

entity_type

string

identification_number

integer

Example

12345678

identification_type

string

Example

national_id

secondary_identification_number

integer

secondary_identification_type

string

status

string

phone_number

string

Example

+254712345678

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

Example

Vendor A Ltd

entity_directors

string

nature_of_business

string

Example

Internet Service Provider

business_type

string

Example

limited_company

entity_address

string

Example

Westlands

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

Example

KES

organization_id

string

Example

9

account_name

string

Example

Vendor A

email

string

Example

vendor-a@acme.co

phone_number

string

Example

+254711000111

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

Example

9f2c61ab4d7e4a0c8b115d3e

phone_number

A token from a phone or phone_status_global check.

string

Example

c41e77d9b0a24f6e89305ab2

tin

A token from a kra_pin or tin_global check.

string

Example

a1b2c3d4e5f6a7b8c9d0e1f2

Responses

200

The updated KYC record.

Media typeapplication/json

object

account_kyc

object

id

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

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

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

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
}