diff --git a/README.md b/README.md index a5996d6..12f6b47 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ func main() { Ref: "FT23001234ABC", Amount: 500, ReceiverName: "YOUR NAME", - ReceiverAccount: "1000017692643", + ReceiverAccount: "1000123456789", }) if err != nil { fmt.Println("API error:", err) @@ -43,6 +43,47 @@ func main() { } ``` +## 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 Network and HTTP errors return as Go `error`. Verification failures (wrong amount, wrong receiver, etc.) are NOT errors — they're returned as `VerifyResult{Verified: false, Error: "..."}`. diff --git a/qbirr.go b/qbirr.go index b4fd14a..f3daaf3 100644 --- a/qbirr.go +++ b/qbirr.go @@ -6,7 +6,7 @@ // Ref: "FT23001234ABC", // Amount: 500, // ReceiverName: "YOUR NAME", -// ReceiverAccount: "1000017692643", +// ReceiverAccount: "1000123456789", // }) // if err != nil { return err } // if r.Verified { fmt.Println("Paid by", r.Payer) }