# qbirr-go Go client for the qbirr Ethiopian bank verification API. ## Install ```bash go get github.com/qbirr/sdk-go ``` ## Quick start ```go package main import ( "context" "fmt" "os" "github.com/qbirr/sdk-go" ) func main() { qb := qbirr.New(os.Getenv("QBIRR_API_KEY")) r, err := qb.Verify(context.Background(), qbirr.VerifyRequest{ Provider: qbirr.ProviderCBE, Ref: "FT23001234ABC", Amount: 500, ReceiverName: "YOUR NAME", ReceiverAccount: "1000123456789", }) if err != nil { fmt.Println("API error:", err) return } if r.Verified { fmt.Printf("✓ Paid by %s, amount: %.2f\n", r.Payer, r.Amount) } else { fmt.Println("✗", r.Error) } } ``` ## 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: "..."}`. ```go var apiErr *qbirr.APIError if errors.As(err, &apiErr) { fmt.Println("HTTP status:", apiErr.Status) } ``` ## License MIT