KRA Payments API (PRN Generation)

Generate Payment Reference Numbers (PRNs) for remitting withholding taxes to KRA. Supports Income Tax (IT) Withholding, Rental Income Withholding, and VAT Withholding.

Table of Contents

1. Overview
2. Request Structure
3. Income Tax Withholding
4. Rental Income Withholding
5. VAT Withholding
6. Nature of Transaction Codes
7. Tax Rates Reference

Overview

Required Scope

Endpoint Summary

What Is a PRN?

A Payment Reference Number (PRN) is a unique identifier generated by KRA that must accompany every tax payment. PRNs are required when remitting withholding taxes to KRA via banks or mobile money.

Request Structure

All three withholding tax endpoints share the same request structure with two sections:

{
  "transactionHeader": {
    "withholderPin": "...",
    "transactionUniqueNo": "...",
    "noOfTransactions": 1,
    "taxObligation": "...",
    "taxPeriodFrom": "...",
    "taxPeriodTo": "...",
    "totalGrossAmount": 0,
    "totalTaxAmount": 0
  },
  "transactionDetails": [
    {
      "payeePIN": "...",
      "payeeName": "...",
      "natureOfTransaction": "...",
      "grossAmount": 0,
      "taxRate": 0,
      "taxAmount": 0,
      "invoiceNumber": "...",
      "invoiceDate": "..."
    }
  ]
}

Transaction Header Fields

Transaction Details Fields

Note: The taxObligation field is set automatically by Salami: WHTIT for IT, WHTRENTAL for Rental, WHTVAT for VAT. You can override it if needed.

Income Tax Withholding

Generate a PRN for withholding income tax.

Endpoint: POST /api/kra/payments/it-withholding

Required Scope: kra:payments

Auto-set: taxObligation = "WHTIT"

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/payments/it-withholding \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionHeader": {
      "withholderPin": "P051234567A",
      "transactionUniqueNo": "WHT-IT-2026-001",
      "noOfTransactions": 2,
      "taxObligation": "WHTIT",
      "taxPeriodFrom": "2026-03-01",
      "taxPeriodTo": "2026-03-31",
      "totalGrossAmount": 350000.00,
      "totalTaxAmount": 17500.00
    },
    "transactionDetails": [
      {
        "payeePIN": "A009876543B",
        "payeeName": "CONSULTING FIRM LTD",
        "natureOfTransaction": "WHT_MANAGEMENT_FEE",
        "grossAmount": 200000.00,
        "taxRate": 5,
        "taxAmount": 10000.00,
        "invoiceNumber": "INV-2026-0045",
        "invoiceDate": "2026-03-15"
      },
      {
        "payeePIN": "B001122334C",
        "payeeName": "AUDIT PARTNERS LLP",
        "natureOfTransaction": "WHT_PROFESSIONAL_FEE",
        "grossAmount": 150000.00,
        "taxRate": 5,
        "taxAmount": 7500.00,
        "invoiceNumber": "INV-2026-0046",
        "invoiceDate": "2026-03-20"
      }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "PRN": "KRA2026000123456",
    "TransactionUniqueNo": "WHT-IT-2026-001",
    "TaxObligation": "WHTIT",
    "TotalGrossAmount": 350000.00,
    "TotalTaxAmount": 17500.00,
    "DueDate": "2026-04-20",
    "Status": "Generated",
    "GeneratedAt": "2026-03-29T12:00:00Z"
  },
  "message": "PRN generated successfully"
}

Rental Income Withholding

Generate a PRN for withholding tax on rental income.

Endpoint: POST /api/kra/payments/rental-withholding

Required Scope: kra:payments

Auto-set: taxObligation = "WHTRENTAL"

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/payments/rental-withholding \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionHeader": {
      "withholderPin": "P051234567A",
      "transactionUniqueNo": "WHT-RENT-2026-001",
      "noOfTransactions": 1,
      "taxObligation": "WHTRENTAL",
      "taxPeriodFrom": "2026-03-01",
      "taxPeriodTo": "2026-03-31",
      "totalGrossAmount": 500000.00,
      "totalTaxAmount": 37500.00
    },
    "transactionDetails": [
      {
        "payeePIN": "C005566778D",
        "payeeName": "PROPERTY OWNER",
        "natureOfTransaction": "WHT_RENTAL_INCOME",
        "grossAmount": 500000.00,
        "taxRate": 7.5,
        "taxAmount": 37500.00,
        "invoiceNumber": "RENT-MAR-2026",
        "invoiceDate": "2026-03-01"
      }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "PRN": "KRA2026000123457",
    "TransactionUniqueNo": "WHT-RENT-2026-001",
    "TaxObligation": "WHTRENTAL",
    "TotalGrossAmount": 500000.00,
    "TotalTaxAmount": 37500.00,
    "DueDate": "2026-04-20",
    "Status": "Generated",
    "GeneratedAt": "2026-03-29T12:05:00Z"
  },
  "message": "PRN generated successfully"
}

VAT Withholding

Generate a PRN for VAT withholding.

Endpoint: POST /api/kra/payments/vat-withholding

Required Scope: kra:payments

Auto-set: taxObligation = "WHTVAT"

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/payments/vat-withholding \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionHeader": {
      "withholderPin": "P051234567A",
      "transactionUniqueNo": "WHT-VAT-2026-001",
      "noOfTransactions": 1,
      "taxObligation": "WHTVAT",
      "taxPeriodFrom": "2026-03-01",
      "taxPeriodTo": "2026-03-31",
      "totalGrossAmount": 1160000.00,
      "totalTaxAmount": 32000.00
    },
    "transactionDetails": [
      {
        "payeePIN": "A009876543B",
        "payeeName": "SUPPLIER LTD",
        "natureOfTransaction": "WHT_VAT_GENERAL",
        "grossAmount": 1160000.00,
        "taxRate": 2,
        "taxAmount": 32000.00,
        "invoiceNumber": "SUP-INV-2026-089",
        "invoiceDate": "2026-03-18"
      }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "PRN": "KRA2026000123458",
    "TransactionUniqueNo": "WHT-VAT-2026-001",
    "TaxObligation": "WHTVAT",
    "TotalGrossAmount": 1160000.00,
    "TotalTaxAmount": 32000.00,
    "DueDate": "2026-04-20",
    "Status": "Generated",
    "GeneratedAt": "2026-03-29T12:10:00Z"
  },
  "message": "PRN generated successfully"
}

Nature of Transaction Codes

Income Tax Withholding Nature Codes

Rental Withholding Nature Codes

VAT Withholding Nature Codes

Tax Rates Reference

Withholding Tax Rates (Resident)

Withholding Tax Rates (Non-Resident)

Disclaimer: Tax rates are subject to change by KRA. Always verify current rates at kra.go.ke.

Validation Errors

{
  "success": false,
  "message": "Required fields missing: transactionHeader.withholderPin, transactionHeader.totalTaxAmount",
  "error": "validation_error"
}

Status Codes

Best Practices

1. Unique transaction numbers -- Use a consistent scheme (e.g., WHT-IT-YYYY-NNN)
2. Match totals -- Ensure totalGrossAmount and totalTaxAmount in the header match the sum of details
3. Verify payee PINs -- Use the PIN Checker before submitting
4. File within deadline -- WHT must be remitted by the 20th of the following month
5. Store PRNs -- Save the returned PRN for payment and reconciliation
6. Correct tax rates -- Verify the applicable rate based on residency and payment type

Related Documentation

• KRA Overview
• KRA Checkers -- Validate PINs before submitting
• KRA Returns -- Filing tax returns

Back to: KRA Overview | KRA Compliance