qbirr agent c4f97931f3 Document tolerance, max_age_hours and payer_error
The API accepts per-call overrides for the underpayment limit ("25" = 25 ETB,
"1%" = one percent) and the receipt age limit (hours, 0 disables), and returns
payer_error alongside error. None of it was in this SDK.

payer_error is the payer-facing wording: show it to the customer, because error
is written for the merchant and can name their own saved accounts.
2026-10-06 19:34:08 +03:00

qbirr-go

Go client for the qbirr Ethiopian bank verification API.

Install

go get git.qbirr.com/admin/sdk-go

These packages are not on the public registries yet, so the command above installs straight from the repository.

Quick start

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=<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

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: "..."}.

var apiErr *qbirr.APIError
if errors.As(err, &apiErr) {
    fmt.Println("HTTP status:", apiErr.Status)
}

License

MIT

S
Description
qbirr SDK - sdk-go
Readme 42 KiB
Languages
Go 100%