Team KYC

Each Team carries its own KYC. A Team’s KYC tier determines what it can collect and pay out — see KYC tiers & limits. Submit KYC per Team.

There are two ways to get a Team verified:

Attach verification tokens from checks you have already run. The submission is approved immediately, at the tier the tokens justify, with no reviewer involved. This is the fast path.
Submit documents alone. The submission lands as pending and PayHero reviews it asynchronously.

You can do both on one submission — tokens set the tier, documents remain on file.

Submit KYC

Attach identity and (for businesses) entity information to a Team. Document fields under upload_information are references to uploaded files.

curl -X POST "$PH_AUTH_URL/api/v2/account_kycs" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "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",
      "upload_information": {
        "tax_document": "https://cdn.acme.co/kyc/kra-pin.pdf",
        "entity_certificate_document": "https://cdn.acme.co/kyc/cert-incorp.pdf"
      }
    },
    "account_information": {
      "currency": "KES",
      "organization_id": "9",
      "account_name": "Vendor A",
      "email": "vendor-a@acme.co",
      "phone_number": "+254711000111"
    }
  }'

POST /api/v2/account_kycs

Field	Type	Notes
`account_id`	integer	Required — the Team this KYC belongs to.
`entity_type`	string	`individual` or `business`.
`country_code`	string	ISO country code, e.g. `KE`.
`country`	string	Country name.
`kyc_tier`	integer	Target tier for this submission.
`contact_information`	object	Primary contact identity + `upload_information` documents.
`entity_information`	object	Business details (for `entity_type: business`).
`account_information`	object	Snapshot of the Team’s account details.
`kyc_tokens`	object	Verification tokens backing this submission — see below.
`notes`	string	Optional free-text notes.

{
  "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", "phone_number": "+254712345678" },
    "entity_information": { "entity_name": "Vendor A Ltd", "nature_of_business": "Internet Service Provider" },
    "account_information": { "account_name": "Vendor A", "currency": "KES", "email": "vendor-a@acme.co" },
    "created_at": "2026-07-06T09:20:10Z",
    "updated_at": "2026-07-06T09:20:10Z"
  }
}

Attach verification tokens

Run the checks you need through the verification API, then send the lookup_id each one returned under kyc_tokens. All three slots are optional.

curl -X POST "$PH_AUTH_URL/api/v2/account_kycs" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    }
  }'

Slot	Accepts a token from	Run it with
`kyc_tokens.national_id`	`national_id_*`, `nin`	Identity checks
`kyc_tokens.phone_number`	`phone`, `phone_status_global`	Phone lookup
`kyc_tokens.tin`	`kra_pin`, `tin_global`	Business checks

What the tokens are worth

The tier comes from what the tokens prove, not from the kyc_tier you ask for:

Tokens attached	Resulting tier
Phone number alone	2
National ID alone	2
National ID + company tax ID (`actor_type: "C"`)	3
National ID + individual tax ID (`actor_type: "I"`)	2
Tokens whose checks came back `not_verified`	No change — goes to review

Most businesses send a national ID plus a KRA PIN, which reaches tier 3 when the PIN belongs to a company.

The response

An approved submission carries verification_information — the resolved record of what each token proved, kept for audit:

{
  "account_kyc": {
    "id": 501,
    "account_id": 63,
    "status": "approved",
    "kyc_tier": 3,
    "verification_information": {
      "actor_type": "C",
      "verified_kyc_tier": 3,
      "verifications": [
        {
          "kind": "national_id",
          "token": "9f2c61ab4d7e4a0c8b115d3e",
          "check": "national_id_ke",
          "category": "national_id",
          "verified": true,
          "actor_type": "I",
          "subject_name": "JANE WANJIRU DOE",
          "identifier_masked": "28••••02"
        },
        {
          "kind": "tin",
          "token": "a1b2c3d4e5f6a7b8c9d0e1f2",
          "check": "kra_pin",
          "category": "tax_id",
          "verified": true,
          "actor_type": "C",
          "subject_name": "ACME TRADING LIMITED",
          "identifier_masked": "P00•••••00X"
        }
      ]
    }
  }
}

PayHero resolves every token against Axxa Connect before accepting it. A token that was never issued is rejected — you cannot self-assign a tier by inventing one.

{
  "error_code": "invalid_argument",
  "message": "kyc_tokens.tin is not a verification token issued by Axxa Connect"
}

Upgrade a Team’s tier

Raise an already-approved Team to a higher tier. Attach tokens covering the tier you are asking for and the upgrade is granted immediately; otherwise it queues for review.

curl -X POST "$PH_AUTH_URL/api/v2/account_kycs/upgrade" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 63,
    "upgrade_information": {
      "upgrade_to": 3,
      "upgrade_notes": "Adding third-party collections"
    },
    "kyc_tokens": {
      "national_id": "9f2c61ab4d7e4a0c8b115d3e",
      "tin": "a1b2c3d4e5f6a7b8c9d0e1f2"
    }
  }'

POST /api/v2/account_kycs/upgrade

Field	Type	Notes
`account_id`	integer	Required — the Team to upgrade.
`upgrade_information.upgrade_to`	integer	The tier being requested.
`upgrade_information.upgrade_notes`	string	Optional context for the reviewer.
`entity_information`	object	Optional — amend business details at the same time.
`kyc_tokens`	object	Tokens backing the requested tier.

The Team must already be approved — a pending, in-review or rejected submission has to be settled first.

Update KYC

Amend a submission — for example to attach a missing document or correct a detail. Identify the record with the id in the path.

curl -X PUT "$PH_AUTH_URL/api/v2/account_kycs/501" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 501,
    "entity_type": "business",
    "country_code": "KE",
    "country": "Kenya",
    "kyc_tier": 3,
    "entity_information": {
      "entity_name": "Vendor A Ltd",
      "upload_information": {
        "proof_of_address_document": "https://cdn.acme.co/kyc/utility-bill.pdf"
      }
    }
  }'

PUT /api/v2/account_kycs/{id} — accepts the same fields as Submit and returns the updated { "account_kyc": { … } }.