# Telebirr

> Detail page: URL format, reference shape, return type, and quirks for telebirr receipts.

Telebirr's official receipt endpoint at `transactioninfo.ethiotelecom.et` returns a bilingual (Amharic + English) HTML page; we scrape it with regex and return a structured object.

## URL format

```
https://transactioninfo.ethiotelecom.et/receipt/<REFERENCE>
```

| Part | Pattern | Example |
| ------------- | --------------------- | --------------------------------- |
| host | literal | `transactioninfo.ethiotelecom.et` |
| `<REFERENCE>` | 8–14 chars `[A-Z0-9]` | `ABCD1234EF` |

You can also pass just the reference via `{ "reference": "ABCD1234EF" }`; telebirr is the only provider where the bare-reference shortcut works directly through `/api/verify`.

## Return type

`receipt.source === "telebirr-html"`. All fields are optional strings, present when the upstream HTML included them.

```ts
interface TelebirrReceipt {
	source: 'telebirr-html';

	// Counterparties
	payerName?: string;
	payerTelebirrNo?: string; // masked: "251********"
	payerAccountType?: string; // e.g. "Individual Customer"
	creditedPartyName?: string;
	creditedPartyAccountNo?: string; // masked

	// Transaction header
	transactionStatus?: string; // "Completed" | …
	receiptNo?: string; // matches the URL reference
	paymentDate?: string; // "DD-MM-YYYY HH:MM:SS"

	// Amounts (strings; they include the " Birr" suffix as telebirr renders it)
	settledAmount?: string;
	serviceFee?: string;
	serviceFeeVAT?: string;
	totalPaidAmount?: string;

	// Payment metadata
	paymentReason?: string;
	paymentMode?: string;
	paymentChannel?: string;
}
```

### Sample (placeholder values)

```json
{
	"source": "telebirr-html",
	"payerName": "<payer name>",
	"payerTelebirrNo": "251********",
	"payerAccountType": "Individual Customer",
	"creditedPartyName": "<recipient name>",
	"creditedPartyAccountNo": "251********",
	"transactionStatus": "Completed",
	"receiptNo": "ABCD1234EF",
	"paymentDate": "01-01-2026 00:00:00",
	"settledAmount": "100 Birr",
	"serviceFee": "1.74 Birr",
	"serviceFeeVAT": "0.26 Birr",
	"totalPaidAmount": "102 Birr",
	"paymentReason": "Send Money to Registered Customer",
	"paymentMode": "telebirr",
	"paymentChannel": "API/App"
}
```

## Quirks

- **Bilingual labels**: the upstream label format is `<Amharic>/<English>` (e.g. `የክፍያው ሁኔታ/transaction status`). We anchor on the English tail only to sidestep Unicode NFC/NFD drift on the Amharic prefix.
- **Amount strings carry the unit**: `"100 Birr"`, not a number. If you need a numeric, strip the trailing ` Birr` client-side.
- **One row in the HTML is malformed**: the `transaction status` `<td>` is missing its closing tag in the upstream output. Our parser tolerates this; it's why we don't reject receipts that look incomplete in raw HTML.
- **Rate limit**: telebirr's edge rate-limits aggressively. links.et's outbound queue throttles to ~1 request every 1.5 s for this host, with adaptive backoff on `429`. You won't usually hit this from `/api/verify` because cache hits don't touch upstream.