Docs + scrub: neutral example account number, CBE reference formats, webhooks, quota
- The example account number in the README and in the source docblock was a REAL account number. Replaced with an obviously fake one (1000123456789). The same scrub had already been applied to sdks/ in qbirr-saas; this repo had drifted from it. - Document that CBE accepts the full receipt link, the "v2-" token and the bare token as the SAME payment. qbirr reduces them to one identity, so a receipt cannot be verified twice by presenting it differently. Case is ignored for that check. - Document the webhook contract: `verification.created` fires for BOTH outcomes so always read data.verified; data.client_ref echoes the tag your own upload sent (null if you did not send one); a 4xx response is final and is NOT retried, while 5xx / timeouts are retried with exponential backoff. - Document that only verified lookups count against the monthly quota. - sdk-node: the committed dist/ comment blocks were updated to match src. The change is inside comments only — no executable code differs.
This commit is contained in:
@@ -22,7 +22,7 @@ const r = await qb.verify({
|
|||||||
ref: 'FT23001234ABC',
|
ref: 'FT23001234ABC',
|
||||||
amount: 500,
|
amount: 500,
|
||||||
receiverName: 'YOUR FULL NAME',
|
receiverName: 'YOUR FULL NAME',
|
||||||
receiverAccount: '1000017692643',
|
receiverAccount: '1000123456789',
|
||||||
});
|
});
|
||||||
|
|
||||||
if (r.verified) {
|
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 }`.
|
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=<hex> # HMAC-SHA256(secret, "<timestamp>.<raw body>")
|
||||||
|
X-Qbirr-Timestamp: <unix seconds>
|
||||||
|
X-Qbirr-Event: verification.created
|
||||||
|
X-Qbirr-Delivery: <delivery id>
|
||||||
|
```
|
||||||
|
|
||||||
|
`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
|
## 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: '...' }`.
|
`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: '...' }`.
|
||||||
|
|||||||
Vendored
+2
-2
@@ -8,7 +8,7 @@
|
|||||||
* ref: 'FT23001234ABC',
|
* ref: 'FT23001234ABC',
|
||||||
* amount: 500,
|
* amount: 500,
|
||||||
* receiverName: 'YOUR NAME',
|
* receiverName: 'YOUR NAME',
|
||||||
* receiverAccount: '1000017692643',
|
* receiverAccount: '1000123456789',
|
||||||
* });
|
* });
|
||||||
* console.log(r.verified, r.payer);
|
* console.log(r.verified, r.payer);
|
||||||
*
|
*
|
||||||
@@ -84,7 +84,7 @@ export class Qbirr {
|
|||||||
* provider: 'cbe',
|
* provider: 'cbe',
|
||||||
* amount: 999,
|
* amount: 999,
|
||||||
* receiverName: 'YOUR NAME',
|
* receiverName: 'YOUR NAME',
|
||||||
* receiverAccount: '1000017692643',
|
* receiverAccount: '1000123456789',
|
||||||
* file: buf,
|
* file: buf,
|
||||||
* filename: 'receipt.pdf',
|
* filename: 'receipt.pdf',
|
||||||
* contentType: 'application/pdf',
|
* contentType: 'application/pdf',
|
||||||
|
|||||||
Vendored
+2
-2
@@ -8,7 +8,7 @@
|
|||||||
* ref: 'FT23001234ABC',
|
* ref: 'FT23001234ABC',
|
||||||
* amount: 500,
|
* amount: 500,
|
||||||
* receiverName: 'YOUR NAME',
|
* receiverName: 'YOUR NAME',
|
||||||
* receiverAccount: '1000017692643',
|
* receiverAccount: '1000123456789',
|
||||||
* });
|
* });
|
||||||
* console.log(r.verified, r.payer);
|
* console.log(r.verified, r.payer);
|
||||||
*
|
*
|
||||||
@@ -120,7 +120,7 @@ export declare class Qbirr {
|
|||||||
* provider: 'cbe',
|
* provider: 'cbe',
|
||||||
* amount: 999,
|
* amount: 999,
|
||||||
* receiverName: 'YOUR NAME',
|
* receiverName: 'YOUR NAME',
|
||||||
* receiverAccount: '1000017692643',
|
* receiverAccount: '1000123456789',
|
||||||
* file: buf,
|
* file: buf,
|
||||||
* filename: 'receipt.pdf',
|
* filename: 'receipt.pdf',
|
||||||
* contentType: 'application/pdf',
|
* contentType: 'application/pdf',
|
||||||
|
|||||||
Vendored
+2
-2
@@ -8,7 +8,7 @@
|
|||||||
* ref: 'FT23001234ABC',
|
* ref: 'FT23001234ABC',
|
||||||
* amount: 500,
|
* amount: 500,
|
||||||
* receiverName: 'YOUR NAME',
|
* receiverName: 'YOUR NAME',
|
||||||
* receiverAccount: '1000017692643',
|
* receiverAccount: '1000123456789',
|
||||||
* });
|
* });
|
||||||
* console.log(r.verified, r.payer);
|
* console.log(r.verified, r.payer);
|
||||||
*
|
*
|
||||||
@@ -84,7 +84,7 @@ export class Qbirr {
|
|||||||
* provider: 'cbe',
|
* provider: 'cbe',
|
||||||
* amount: 999,
|
* amount: 999,
|
||||||
* receiverName: 'YOUR NAME',
|
* receiverName: 'YOUR NAME',
|
||||||
* receiverAccount: '1000017692643',
|
* receiverAccount: '1000123456789',
|
||||||
* file: buf,
|
* file: buf,
|
||||||
* filename: 'receipt.pdf',
|
* filename: 'receipt.pdf',
|
||||||
* contentType: 'application/pdf',
|
* contentType: 'application/pdf',
|
||||||
|
|||||||
+2
-2
@@ -8,7 +8,7 @@
|
|||||||
* ref: 'FT23001234ABC',
|
* ref: 'FT23001234ABC',
|
||||||
* amount: 500,
|
* amount: 500,
|
||||||
* receiverName: 'YOUR NAME',
|
* receiverName: 'YOUR NAME',
|
||||||
* receiverAccount: '1000017692643',
|
* receiverAccount: '1000123456789',
|
||||||
* });
|
* });
|
||||||
* console.log(r.verified, r.payer);
|
* console.log(r.verified, r.payer);
|
||||||
*
|
*
|
||||||
@@ -186,7 +186,7 @@ export class Qbirr {
|
|||||||
* provider: 'cbe',
|
* provider: 'cbe',
|
||||||
* amount: 999,
|
* amount: 999,
|
||||||
* receiverName: 'YOUR NAME',
|
* receiverName: 'YOUR NAME',
|
||||||
* receiverAccount: '1000017692643',
|
* receiverAccount: '1000123456789',
|
||||||
* file: buf,
|
* file: buf,
|
||||||
* filename: 'receipt.pdf',
|
* filename: 'receipt.pdf',
|
||||||
* contentType: 'application/pdf',
|
* contentType: 'application/pdf',
|
||||||
|
|||||||
Reference in New Issue
Block a user