From 7f9827cddfd4d3109db6a5128be30db25fbd9248 Mon Sep 17 00:00:00 2001 From: admin Date: Tue, 6 Oct 2026 01:05:08 +0300 Subject: [PATCH] Docs + scrub: neutral example account number, CBE reference formats, webhooks, quota MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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. --- README.md | 43 ++++++++++++++++++++++++++++++++++++++++++- src/Qbirr.php | 2 +- 2 files changed, 43 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8525b96..2b7feca 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ $r = $qb->verify([ 'ref' => 'FT23001234ABC', 'amount' => 500, 'receiver_name' => 'YOUR FULL NAME', - 'receiver_account' => '1000017692643', + 'receiver_account' => '1000123456789', ]); if ($r['verified']) { @@ -48,6 +48,47 @@ require 'vendor/autoload.php'; $r = (new Qbirr\Qbirr(getenv('QBIRR_API_KEY')))->verify([...]); ``` +## 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 ```php diff --git a/src/Qbirr.php b/src/Qbirr.php index 6f0d2e4..6110b56 100644 --- a/src/Qbirr.php +++ b/src/Qbirr.php @@ -8,7 +8,7 @@ * 'ref' => 'FT23001234ABC', * 'amount' => 500, * 'receiver_name' => 'YOUR NAME', - * 'receiver_account' => '1000017692643', + * 'receiver_account' => '1000123456789', * ]); * if ($r['verified']) echo "Paid by " . $r['payer']; */