diff --git a/README.md b/README.md index 8878ab7..0831813 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ const r = await qb.verify({ ref: 'FT23001234ABC', amount: 500, receiverName: 'YOUR FULL NAME', - receiverAccount: '1000017692643', + receiverAccount: '1000123456789', }); if (r.verified) { @@ -58,6 +58,47 @@ Returns `{ verified, payer, amount, error }`. Returns the current month's `{ used, limit, remaining, plan, period_start, period_end }`. +## Reference formats + +`ref` accepts whatever the customer pasted. For **CBE**, all of these are the +*same* payment, and qbirr reduces them to a single identity so one receipt +cannot be verified twice: + +| What the customer pasted | Example | +|---|---| +| The full receipt link | `https://mbreciept.cbe.com.et/v2-hfHCxHoqlCB1LfGG6kJY` | +| The token with its `v2-` prefix | `v2-hfHCxHoqlCB1LfGG6kJY` | +| Just the token | `hfHCxHoqlCB1LfGG6kJY` | +| The legacy `FT…` reference | `FT262693ZS18` | + +Case is ignored when deciding whether a receipt has already been used. **Awash** +takes the SMS URL or its token; **eBirr** takes the URL or `"tenant/token"`. + +## Webhooks + +Subscribe from the dashboard. qbirr POSTs `verification.created` for **both** +outcomes, so always read `data.verified` — never treat delivery alone as payment. + +``` +X-Qbirr-Signature: sha256= # HMAC-SHA256(secret, ".") +X-Qbirr-Timestamp: +X-Qbirr-Event: verification.created +X-Qbirr-Delivery: +``` + +`data.client_ref` echoes the tag your own upload sent, so an order can be found +without inferring it from the provider and amount. It is `null` if you did not +send one. + +Answer `2xx` once you have processed the event. A **4xx is final** — qbirr will +not retry a request your endpoint refused. Return **5xx** (or time out) to have +it retried with exponential backoff. + +## Quota + +Only **verified** lookups count against your monthly quota. A failed, retryable +or duplicate lookup does not consume quota. + ## Errors `QbirrError` is thrown for network failures, HTTP 4xx/5xx, or non-JSON responses. **Verification failures** (wrong amount, wrong receiver, expired receipt) are NOT thrown — they're returned as `{ verified: false, error: '...' }`. diff --git a/dist/index.cjs b/dist/index.cjs index fd3fbb6..85dad49 100644 --- a/dist/index.cjs +++ b/dist/index.cjs @@ -8,7 +8,7 @@ * ref: 'FT23001234ABC', * amount: 500, * receiverName: 'YOUR NAME', - * receiverAccount: '1000017692643', + * receiverAccount: '1000123456789', * }); * console.log(r.verified, r.payer); * @@ -84,7 +84,7 @@ export class Qbirr { * provider: 'cbe', * amount: 999, * receiverName: 'YOUR NAME', - * receiverAccount: '1000017692643', + * receiverAccount: '1000123456789', * file: buf, * filename: 'receipt.pdf', * contentType: 'application/pdf', diff --git a/dist/index.d.ts b/dist/index.d.ts index 0443f95..a1328e4 100644 --- a/dist/index.d.ts +++ b/dist/index.d.ts @@ -8,7 +8,7 @@ * ref: 'FT23001234ABC', * amount: 500, * receiverName: 'YOUR NAME', - * receiverAccount: '1000017692643', + * receiverAccount: '1000123456789', * }); * console.log(r.verified, r.payer); * @@ -120,7 +120,7 @@ export declare class Qbirr { * provider: 'cbe', * amount: 999, * receiverName: 'YOUR NAME', - * receiverAccount: '1000017692643', + * receiverAccount: '1000123456789', * file: buf, * filename: 'receipt.pdf', * contentType: 'application/pdf', diff --git a/dist/index.js b/dist/index.js index fd3fbb6..85dad49 100644 --- a/dist/index.js +++ b/dist/index.js @@ -8,7 +8,7 @@ * ref: 'FT23001234ABC', * amount: 500, * receiverName: 'YOUR NAME', - * receiverAccount: '1000017692643', + * receiverAccount: '1000123456789', * }); * console.log(r.verified, r.payer); * @@ -84,7 +84,7 @@ export class Qbirr { * provider: 'cbe', * amount: 999, * receiverName: 'YOUR NAME', - * receiverAccount: '1000017692643', + * receiverAccount: '1000123456789', * file: buf, * filename: 'receipt.pdf', * contentType: 'application/pdf', diff --git a/src/index.ts b/src/index.ts index 3d09dba..f63176c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -8,7 +8,7 @@ * ref: 'FT23001234ABC', * amount: 500, * receiverName: 'YOUR NAME', - * receiverAccount: '1000017692643', + * receiverAccount: '1000123456789', * }); * console.log(r.verified, r.payer); * @@ -186,7 +186,7 @@ export class Qbirr { * provider: 'cbe', * amount: 999, * receiverName: 'YOUR NAME', - * receiverAccount: '1000017692643', + * receiverAccount: '1000123456789', * file: buf, * filename: 'receipt.pdf', * contentType: 'application/pdf',