Add Reverse Invoice

POST/api/v1/reverse-invoices

In Kenya Revenue Authority eTIMS, a reverse invoice is a sale submitted with rcptTyCd set to 'R' (Return). Use POST {{API_PATH}}/sales with rcptTyCd: 'R' to record a customer return. The payload is identical to a standard sale.

Requires x-api-key

http://localhost:8100/api/v1/reverse-invoices

How Reverse Invoices Work in Kenya Revenue Authority eTIMS

Field	Type	Required	Description
rcptTyCd	string	Required	Must be 'R' for a return/reverse invoice.
orgInvcNo	number	Required	Original invoice number being reversed.
invcNo	string	Required	New invoice number for this return transaction.
salesDt	string	Required	Date of the return in YYYYMMDD format.
salesSttsCd	string	Required	Sales status, use '02' for approved.
pmtTyCd	string	Required	Payment method for the refund.
totTaxblAmt	number	Required	Taxable amount being reversed (negative or positive, Kenya Revenue Authority accepts positive values).
totTax	number	Required	Tax amount being reversed.
totAmt	number	Required	Total amount being reversed.

Request

{
  "transaction": {
    "invcNo": "RET-2024-001",
    "orgInvcNo": 42,
    "salesDt": "20240116",
    "pmtTyCd": "09",
    "rcptTyCd": "R",
    "salesSttsCd": "02",
    "currency": "KES",
    "exchangeRate": 1,
    "destnCountryCd": "KE",
    "totTaxblAmt": 4310.34,
    "totTax": 689.66,
    "totAmt": 5000
  },
  "lineItems": [
    {
      "itemCd": "SV0000000Z001",
      "itemNm": "Monthly SaaS Subscription",
      "qtyUnitCd": "U",
      "qty": 1,
      "prc": 5000,
      "taxTyCd": "B",
      "taxblAmt": 4310.34,
      "taxAmt": 689.66,
      "totAmt": 5000
    }
  ]
}

Response

{
  "success": true,
  "message": "Return submitted to Kenya Revenue Authority.",
  "data": {
    "cisInvcNo": 44,
    "intrlData": "AbCdEfGhIjKlMnOpQrStUvWxYz...",
    "rcptSign": "XxXxXxXxXxXxXxXxXxXxXxXx...",
    "sdcDateTime": "20240116110000",
    "totRcptNo": 44
  }
}

curl -X POST http://localhost:8100/api/v1/sales \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "transaction": {
      "invcNo": "RET-2024-001",
      "orgInvcNo": 42,
      "salesDt": "20240116",
      "pmtTyCd": "09",
      "rcptTyCd": "R",
      "salesSttsCd": "02",
      "currency": "KES",
      "exchangeRate": 1,
      "destnCountryCd": "KE",
      "totTaxblAmt": 4310.34,
      "totTax": 689.66,
      "totAmt": 5000
    },
    "lineItems": [{
      "itemCd": "SV0000000Z001",
      "itemNm": "Monthly SaaS Subscription",
      "qtyUnitCd": "U",
      "qty": 1,
      "prc": 5000,
      "taxTyCd": "B",
      "taxblAmt": 4310.34,
      "taxAmt": 689.66,
      "totAmt": 5000
    }]
  }'