Documentation

API reference

Base URL: https://verify.qbirr.com

Stable since v1. Backwards-compatible changes are added regularly; breaking changes get a new path prefix.

Authentication

Every request needs your API key in the X-API-Key header. The key looks like abc12345.LONGRANDOMSECRET — send the whole string.

POST /api/v1/verify

Verifies one transaction. Returns verified: true only if the receipt is real, the amount matches, and the receiver name matches.

curl -X POST https://verify.qbirr.com/api/v1/verify \
  -H "X-API-Key: $QBIRR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "cbe",
    "ref": "FT23001234ABC",
    "amount": 500,
    "receiver_name": "YOUR FULL NAME",
    "receiver_account": "1000123456789"
  }'

import { Qbirr } from '@qbirr/sdk';

const qb = new Qbirr({ apiKey: process.env.QBIRR_API_KEY });

const r = await qb.verify({
  provider: 'cbe',
  ref: 'FT23001234ABC',
  amount: 500,
  receiverName: 'YOUR FULL NAME',
  receiverAccount: '1000123456789',
});
console.log(r.verified ? '✓ ' + r.payer : '✗ ' + r.error);

from qbirr import Qbirr

qb = Qbirr(api_key=os.environ["QBIRR_API_KEY"])
r = qb.verify(
    provider="cbe",
    ref="FT23001234ABC",
    amount=500,
    receiver_name="YOUR FULL NAME",
    receiver_account="1000123456789",
)
print(r.verified, r.payer)

use Qbirr\Qbirr;

$qb = new Qbirr($_ENV['QBIRR_API_KEY']);
$r  = $qb->verify([
    'provider'         => 'cbe',
    'ref'              => 'FT23001234ABC',
    'amount'           => 500,
    'receiver_name'    => 'YOUR FULL NAME',
    'receiver_account' => '1000123456789',
]);
echo $r['verified'] ? "✓ {$r['payer']}" : "✗ {$r['error']}";

qb := qbirr.New(os.Getenv("QBIRR_API_KEY"))
r, err := qb.Verify(ctx, qbirr.VerifyRequest{
    Provider:        qbirr.ProviderCBE,
    Ref:             "FT23001234ABC",
    Amount:          500,
    ReceiverName:    "YOUR FULL NAME",
    ReceiverAccount: "1000123456789",
})
if err != nil { panic(err) }
fmt.Println(r.Verified, r.Payer)

Request fields

Response

{
  "verified":        true,
  "payer":           "JANE DOE",
  "amount":          500,
  "paid_amount":     500,
  "error":           "",
  "retryable":       false,
  "code":            null,
  "receiver_source": "settings"
}

HTTP is 200 whether the payment verified or not — always read verified, never the status code.

The three fields that stop you rejecting honest payments

Reason codes

The request-level failures (MISSING_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, NO_PLAN, PLAN_EXPIRED, QUOTA_EXCEEDED, INVALID_REQUEST, REQUEST_TOO_LARGE) also carry a code and come with a non-200 status.

Sandbox (test without a bank)

Any ref starting with TEST- returns a canned result without contacting a bank. It does not consume your quota, and the response carries "sandbox": true so you can never mistake a fixture for a real verdict. Use it to build and test your integration before a single real payment arrives.

# always verifies
curl -X POST https://qbirr.com/api/v1/verify -H "X-API-Key: $QBIRR_API_KEY" \
  -d '{"provider":"cbe","ref":"TEST-OK","amount":500}'

# and one for each failure you should handle
TEST-EXPIRED          -> RECEIPT_EXPIRED
TEST-WRONG-AMOUNT     -> AMOUNT_MISMATCH
TEST-NOT-FOUND        -> RECEIPT_NOT_FOUND
TEST-WRONG-RECEIVER   -> RECEIVER_MISMATCH
TEST-DUPLICATE        -> DUPLICATE_REFERENCE

GET /api/v1/usage

Returns the current calendar month's quota status.

curl https://verify.qbirr.com/api/v1/usage -H "X-API-Key: $QBIRR_API_KEY"

{
  "used": 124,
  "limit": 1000,
  "remaining": 876,
  "plan": "Starter",
  "period_start": "2026-05-01T00:00:00Z",
  "period_end":   "2026-06-01T00:00:00Z"
}

HTTP status codes

Provider notes

Official SDKs

For Ruby, .NET, Java, Rust, or anything else — see the cURL example above; it's the same HTTP shape everywhere.

Best practices

• Verify server-side. Never put your API key in browser/mobile code.
• Treat retryable: true as "no answer", not "no payment". If we could not reach the bank, retry — or fall back to manual review. Never reject an order on a UPSTREAM_UNAVAILABLE.
• Store the ref on the order. qbirr enforces uniqueness, but checking on your side too prevents accidental double-verifies.
• Beware retrying a call that already succeeded. If a request times out after we processed it, the retry comes back as verified: false with code DUPLICATE_REFERENCE — because the reference is already used for your account. Check for DUPLICATE_REFERENCE before treating that as a failed payment, and look up the payment in your dashboard. Per-request idempotency keys are not yet available.
• Don't auto-refund on verified: false — false negatives are possible if a provider's receipt page is briefly down.
• Cache the verified result in your order record. Don't re-call /verify for the same payment.
• Read receiver_source while you're integrating. If it says "none", you have no identity check at all — send receiver_name, or save your account under Pay-by-link & QR.