Risiti eTIMS API Reference
Build with the Risiti eTIMS API: sandbox keys, merchant setup, KRA codes, invoices, credit notes, idempotency, submission states and signed webhooks.
This reference describes Risiti eTIMS API 1.0.0. The interactive endpoint explorer loads on this page. The downloadable OpenAPI contract contains request schemas, response fields and examples.
HTTP regression evidence — 4 October 2026
HTTP regression coverage exercises both products' namespaced resource creation, listing and detail, merchant ownership, scopes, replay conflicts, buyer consent and immutable audit events. Platform initialization uses mocked upstream KRA responses and checks business/device binding and encrypted credentials. These tests do not prove live KRA acceptance or production readiness.
Sandbox fiscal processing and buyer acceptance are simulations. The public webhook registration API does not accept buyer-invoice event subscriptions; internal event support is not public subscription availability.
Start with a complete sandbox workflow
- Choose Direct API for one verified business or Platform API for connected merchants, then create a sandbox key. Keep the key on your server.
- For Platform API, create each merchant and store its merchant_id. Direct API uses the verified workspace business and has no merchant-creation endpoint. Resolve KRA reference codes and register the items or services you will invoice.
- Submit an invoice with a stable external identifier and a unique Idempotency-Key.
- Follow the submission lifecycle or signed webhooks. A 202 response confirms durable acceptance by Risiti; it does not confirm completed KRA processing.
- Test credit notes, validation failures and reconciliation before requesting live access. Each merchant needs its confirmed KRA connection before live fiscal submission.
Environments and authentication
- Sandbox:
https://sandbox-api.getrisiti.com/v1/platform - Production:
https://api.getrisiti.com/v1/platform
The servers above use the Platform API namespace. Direct API uses https://sandbox-api.getrisiti.com/v1/direct in sandbox and https://api.getrisiti.com/v1/direct in production. Its separate contract omits merchant-management endpoints.
Send Authorization: Bearer with the appropriate sandbox or live key and Content-Type: application/json. Platform keys manage multiple merchants and require merchant_id where documented; Direct API keys identify the one verified workspace business. Required scopes are documented for each operation.
Submission status and safe retries
Use data.submission as the KRA delivery lifecycle. queued, submitting_to_kra and waiting_for_kra are ongoing states. completed is successful. For action_required, follow submission.message: the request may need corrected information or support after exhausted retries. Check submission.terminal and submission.succeeded before marking a transaction complete.
Retain the resource id, external_id and request_id. Risiti owns retries for queued work. Invoice creation and the other resource-creation operations that declare Idempotency-Key support stored replays; changed JSON with the same key returns a conflict. Merchant and webhook setup do not share that replay guarantee: reconcile an uncertain setup response before repeating it. Do not create a duplicate sale while the original submission is waiting.
Platform API endpoint directory
These paths are relative to the Platform API servers above. Methods and summaries come directly from its published OpenAPI contract. Open the interactive explorer for payloads, permissions and error responses, or use the Direct API contract for a single-business integration.
| Method and path | Operation |
|---|---|
| GET /kra/pin-checker | Verify and prefill a KRA taxpayer |
| POST /merchants | Create a merchant |
| GET /merchants | List merchants |
| GET /merchants/{merchantId} | Get a merchant |
| POST /merchants/{merchantId}/etims/initialize | Connect a merchant to KRA eTIMS |
| GET /merchants/{merchantId}/compliance | Get merchant compliance health |
| GET /reference/kra-codes | Find KRA classifications and standard codes |
| POST /invoices | Create and submit an invoice |
| GET /invoices | List invoices |
| GET /invoices/{invoiceId} | Get invoice status and receipt data |
| POST /credit-notes | Issue a credit note against an accepted sales invoice |
| GET /credit-notes | List credit notes |
| GET /credit-notes/{creditNoteId} | Get a credit note and KRA submission status |
| POST /items | Register an item or service |
| GET /items | List merchant items and KRA registration status |
| GET /items/{itemId} | Get an item |
| POST /suppliers | Create a supplier |
| GET /suppliers | List suppliers |
| GET /suppliers/{supplierId} | Get a supplier |
| POST /purchases | Record and submit a supplier purchase |
| GET /purchases | List supplier purchases |
| GET /purchases/{purchaseId} | Get a supplier purchase and KRA status |
| POST /stock-movements | Record a compliant stock movement |
| GET /stock-movements | List stock movements and resulting balances |
| GET /stock-movements/{stockMovementId} | Get a stock movement |
| POST /buyer-invoices | Create a sandbox buyer-initiated invoice |
| GET /buyer-invoices | List buyer-initiated invoices |
| GET /buyer-invoices/{buyerInvoiceId} | Get a buyer invoice and immutable lifecycle events |
| POST /buyer-invoices/{buyerInvoiceId}/consent | Simulate the seller's sandbox consent decision |
| POST /webhook-endpoints | Create a webhook endpoint |
| GET /webhook-endpoints | List webhook endpoints |
| POST /webhook-endpoints/{endpointId}/test | Send a test webhook event |
| GET /api-logs | List API request logs |
Production boundaries
Buyer-initiated invoices are a sandbox preview with detail and consent covered by HTTP regression tests; acceptance is simulated. Live reverse-invoicing transport requires the applicable KRA approval and an approved route configured by Risiti. Sandbox credentials cannot enable production access.
Risiti is a product of PesaStack Limited, independent of the Kenya Revenue Authority. Read the terms, privacy policy and buyer-initiated API scope.