paste-to-verify

Verify Ethiopian CBE and Telebirr payment receipts from a pasted SMS — no bank API keys, no manual review.

When a customer pays, they get an SMS containing a receipt link. This library takes that raw SMS, extracts the link, fetches the authoritative receipt page from the provider's own domain, parses it into a normalized transaction, and runs deterministic checks against what you expected.

npm install paste-to-verify
# CBE receipts additionally need a headless browser (optional peer dependency):
npm install playwright && npx playwright install chromium

Quickstart

import { parseReceipt, verifyTransaction } from 'paste-to-verify';

const transaction = await parseReceipt(pastedSms);

const result = verifyTransaction(transaction, {
  amount: 990, // the principal credited to the receiver
  receiverAccount: '1000212343981', // mask-aware match against e.g. "1****3981"
  maxAgeMinutes: 30,
});

result.verified; // boolean
result.failures; // [{ field, expected, actual, reason }]

transaction.amount is always the principal transferred to the receiver; fees, VAT, levies, totals and balance live under transaction.raw.

No SMS at hand? Start from the receipt link or the transaction id instead:

import { parseReceiptId, parseReceiptUrl } from 'paste-to-verify';

await parseReceiptUrl('https://transactioninfo.ethiotelecom.et/receipt/SAMPLE1234');
await parseReceiptId('telebirr', 'SAMPLE1234'); // CBE: pass the v2-… token from the link

Why a receipt page and not the SMS?

The SMS is easy to fabricate, so it is never trusted as the source of truth. It only supplies the receipt URL and fills fields the page omits — on any overlap the page value wins. Provider URLs are matched by hostname (exact domain or subdomain), so lookalike links in a crafted SMS are rejected.

Providers

| Provider | Host | Receipt page | Fetch strategy | | ------------ | --------------------------------- | -------------------- | ------------------------------------------------- | | Telebirr | transactioninfo.ethiotelecom.et | Server-rendered HTML | fetch + HTML parse (edge-friendly) | | CBE | *.cbe.com.et | JavaScript SPA | Headless browser render (Playwright), then scrape |

On runtimes without a browser (serverless, edge), inject your own renderer:

const transaction = await parseReceipt(sms, {
  render: async (url) => fetchRenderedHtmlSomehow(url), // e.g. a remote browser service
  timeoutMs: 10_000, // optional network-stage deadline (default 30s)
});

Errors

parseReceipt rejects only with typed errors carrying a stable code: URL_NOT_FOUND, PROVIDER_NOT_RECOGNIZED, RECEIPT_FETCH_FAILED, RECEIPT_PARSE_FAILED, BROWSER_UNAVAILABLE. Use the isPasteToVerifyError type guard. verifyTransaction is pure, synchronous and never throws.

import { isPasteToVerifyError } from 'paste-to-verify';

try {
  await parseReceipt(sms);
} catch (error) {
  if (isPasteToVerifyError(error)) console.error(error.code, error.message);
}

Documentation

Full guides — verification checks, error handling, serverless & edge deployment, adding a provider — live in the repository docs.

License

MIT © Biruk Worku