Customer Enrollment & KYC

Retrieve KYC State

Check a customer's overall KYC status, outstanding requirements, and the status of every individual submission

GET /v1/customer/{uuid}/kyc

Use this endpoint to

Poll for KYC approval before generating an account or issuing a card
Show a customer exactly which requirements are still outstanding
Check why a specific submission was rejected so that they can re-submit

Request

Path Parameters

Parameter	Type	Required	Description
`uuid`	string	✅	Customer UUID from enrollment

Code Samples

const axios = require("axios");

const uuid = "42feffe9-d625-412e-bfa5-2f3089a11735";

const response = await axios.get(
  `https://sandbox.hitchpay.ng/v1/customer/${uuid}/kyc`,
  {
    headers: {
      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`
    }
  }
);

console.log(response.data);

<?php

$uuid = "42feffe9-d625-412e-bfa5-2f3089a11735";

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/customer/{$uuid}/kyc",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import requests

uuid = "42feffe9-d625-412e-bfa5-2f3089a11735"

url = f"https://sandbox.hitchpay.ng/v1/customer/{uuid}/kyc"

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

Response

200 — Success

{
  "status": "success",
  "message": "KYC status retrieved successfully.",
  "data": {
    "customer_uuid": "…",
    "customerid": "your-customer-ref-001",
    "overall_kyc_status": "pending",
    "nationality": "GB",
    "outstanding_requirements": ["identity_document", "proof_of_address"],
    "submissions": [
      {
        "type": "passport",
        "status": "approved",
        "reason": null,
        "verified_at": "1782947999",
        "submitted_at": "1782947655"
      },
      {
        "type": "proof_of_address",
        "status": "pending",
        "reason": null,
        "verified_at": null,
        "submitted_at": "1782947700"
      }
    ]
  }
}

Fields

Field	Type	Description
`customer_uuid`	string	Customer id
`customerid`	string	Your reference
`overall_kyc_status`	string	`pending_kyc` (nothing submitted yet), `pending` (submitted, under review), or progresses as reviews resolve
`nationality`	string	Customer's nationality on file
`outstanding_requirements`	array	See table below — derived from `nationality`
`submissions`	array	Each submission's `type`, `status`, `reason` (if rejected), `verified_at`, `submitted_at`

`outstanding_requirements` by nationality

Nationality	Requirements (until each is `approved`)
`NG`	`bvn` and `nin`
Any other	`identity_document` (one of `passport` / `drivers_license` / `national_id`) and `proof_of_address`

Submission `status` values

pending, approved, rejected — a rejected submission carries a reason; you may re-submit that type.

Note: The full customer record (Get Customer) also embeds a kyc array with the submitted documents, where the ID number is masked to the last 4 digits.

Errors

Code	HTTP	Meaning
`NOT_FOUND`	404	Customer not found for your business

Best practice: poll this endpoint after each KYC submission, or subscribe to the KYC Status Update webhook instead of polling continuously.

Questions? Email [email protected]. Also on GitBook.