Verify an Invoice

POST/api/v1/invoice-verifications

Verify the authenticity of an invoice using its receipt signature. Optionally provide the customer Kenya Revenue Authority PIN to verify them against Kenya Revenue Authority records. Returns the taxpayer details if the PIN is registered with Kenya Revenue Authority.

Requires x-api-key

http://localhost:8100/api/v1/invoice-verifications

Headers

Field	Type	Required	Description
x-api-key	string	Required	Your Ushuru API key.
Content-Type	string	Required	application/json

Request Body

Field	Type	Required	Description
orgInvcNo	string	Required	The original invoice number to verify.
rcptSign	string	Required	The receipt signature (rcptSign) from the Kenya Revenue Authority eTIMS response.
pin	string	Optional	Kenya Revenue Authority PIN of the taxpayer to verify. When provided, the PIN is looked up in Kenya Revenue Authority records.

Response Without PIN

When pin is omitted, the response confirms the invoice but does not include taxpayer details:

Request

{
  "orgInvcNo": "INV-2024-001",
  "rcptSign": "XxXxXxXxXxXxXxXxXxXxXxXx...",
  "pin": "A000000000Z"
}

Response

{
  "success": true,
  "data": {
    "verified": true,
    "orgInvcNo": "INV-2024-001",
    "rcptSign": "XxXxXxXxXxXxXxXxXxXxXxXx...",
    "taxpayer": {
      "taxprNm": "BUYER COMPANY LTD",
      "tin": "A000000000Z",
      "bhfId": "00",
      "prvncNm": "NAIROBI"
    },
    "verifiedAt": "2024-01-15T10:30:45.000Z"
  }
}

curl -X POST http://localhost:8100/api/v1/invoice-verifications \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "orgInvcNo": "INV-2024-001",
    "rcptSign": "XxXxXxXxXxXxXxXxXxXxXxXx...",
    "pin": "A000000000Z"
  }'