TypeScript SDK for Receipt Verification

Free TypeScript SDK for verifying Ethiopian bank receipts.

View SDK on GitHub

SDK overview

The cheki TypeScript SDK (npm: cheki-verify) is a typed wrapper around the REST API with methods for single verification, batch verification, bank listing, health checks and receipt download links. It has no runtime dependencies (it uses native fetch), waits up to 65 seconds per attempt, and retries a network error, 5xx or 429 at most once. It is tested against the same API contract fixtures as every other cheki SDK.

Quick start

Import the Cheki class (the base URL defaults to https://cheki.et), create an instance, and call verify with the bank id, the reference and, for CBE or BOA, { accountNumber }. Treat the receipt as paid only when isVerified(result) is true: a 200 response can still be unverified, such as a BOA QR code the bank could not confirm (decodedOnly). API errors throw, so wrap calls in try/catch.

Available methods

The Cheki class has four API methods and one URL helper:

  • verify(bank, reference, options?): verify one receipt; options take accountNumber, phoneNumber or qrData. A receipt link can be passed as the reference
  • verifyBatch(receipts): verify up to 20 receipts in one request (checked before sending); returns results, total, verified, failed and cached
  • getBanks(): all supported banks and wallets; each bank's id is the value to pass as bank
  • getHealth(): per-bank reachability (cached by the server for up to 5 minutes)
  • getReceiptUrl(bank, reference, accountNumber?): builds the /api/receipt link for CBE, Dashen and Zemen (no request is made). A CBE Receipt ID needs no account; an older CBE FT reference does

Frequently asked questions

How do I install the cheki TypeScript SDK?

Run npm install cheki-verify, then import { Cheki } from "cheki-verify". It has no runtime dependencies; it uses the platform's fetch (Node.js 18+).

Can I use the SDK in the browser?

Call it from your server. The hosted API does not send CORS headers on the verify routes, so browser calls to cheki.et are blocked. Your backend also keeps your users' requests under its own per-IP rate limit (verify: 30 per minute).

Does the SDK handle errors?

Yes. Any non-2xx response throws ChekiAPIError with the HTTP status, the server's error text and, for geo-blocked banks, a fallbackUrl. 429 throws ChekiRateLimitError (with the Retry-After seconds) and 413 throws ChekiPayloadTooLargeError. Bad input throws ChekiValidationError before any request, and network failures and timeouts throw ChekiNetworkError and ChekiTimeoutError. A receipt the bank does not have is a 422 ChekiAPIError.

View SDK on GitHub

Open cheki

Related guides