From 4f5d7fd291ec827b830349ed92b6e8a8fc0202ad Mon Sep 17 00:00:00 2001 From: admin Date: Thu, 1 Oct 2026 00:44:06 +0300 Subject: [PATCH] feat: expose paid_amount, retryable, code, receiver_source, sandbox The API returns five fields the SDKs were dropping, so a caller could not act on any of them: retryable TRUE means we could not reach the bank. In that case verified=false is NOT a verdict on the payment -- it is "not checked yet". Retry, or fall back to manual review. Never reject an order on it. Check it BEFORE acting on verified=false. code Stable machine-readable reason; branch on this instead of parsing the human-readable error string. Empty/null on success. RECEIPT_NOT_FOUND, AMOUNT_MISMATCH, RECEIVER_MISMATCH, RECEIPT_EXPIRED, RECEIPT_UNREADABLE, REFERENCE_INVALID, RECEIVER_ACCOUNT_REQUIRED, UNSUPPORTED_INPUT, VERIFICATION_FAILED, DUPLICATE_REFERENCE, UPSTREAM_UNAVAILABLE (retryable). paid_amount What the receipt ACTUALLY shows, so a short payment can be compared to the expected figure rather than only described in prose. receiver_source Which receiver identity was actually checked: 'settings' (your saved dashboard account -- strongest), 'request' (the receiver_name/account you sent), or 'none' (NOTHING was checked: verified=true with 'none' means the reference exists and the amount matches, but says nothing about who received the money). sandbox True only on TEST-... responses. Additive only. Defaults are filled in on the way out so a caller never sees a missing value, including against an API build that predates these fields. --- qbirr.go | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/qbirr.go b/qbirr.go index ebb59e0..b4fd14a 100644 --- a/qbirr.go +++ b/qbirr.go @@ -59,6 +59,40 @@ type VerifyResult struct { Payer string `json:"payer"` Amount float64 `json:"amount"` Error string `json:"error"` + + // PaidAmount is the amount the receipt ACTUALLY shows, in ETB. 0 when + // unreadable. On a short payment compare it to Amount to see what arrived. + PaidAmount float64 `json:"paid_amount"` + + // Retryable TRUE means "we could not reach the bank", so Verified=false is NOT + // a verdict on the payment — it is "not checked yet". Retry, or fall back to + // manual review. NEVER reject an order on this. Check it BEFORE acting on + // Verified=false. + Retryable bool `json:"retryable"` + + // Code is a stable machine-readable reason; branch on this instead of parsing + // Error. Empty on success. Values: RECEIPT_NOT_FOUND, AMOUNT_MISMATCH, + // RECEIVER_MISMATCH, RECEIPT_EXPIRED, RECEIPT_UNREADABLE, REFERENCE_INVALID, + // RECEIVER_ACCOUNT_REQUIRED, UNSUPPORTED_INPUT, VERIFICATION_FAILED, + // DUPLICATE_REFERENCE, UPSTREAM_UNAVAILABLE (the only retryable one). + Code string `json:"code"` + + // ReceiverSource is which receiver identity was actually checked: "settings" + // (your saved account — strongest), "request" (the receiver_name/account you + // sent), or "none" (NOTHING was checked: Verified=true with "none" means the + // reference exists and the amount matches, but says nothing about who + // received the money). + ReceiverSource string `json:"receiver_source"` + + // Sandbox is true only on TEST-... responses. + Sandbox bool `json:"sandbox"` +} + +// IsOutage reports whether this result is "we could not check" rather than a +// verdict on the payment. When true, retry or review manually — do not treat the +// payment as invalid. +func (r VerifyResult) IsOutage() bool { + return !r.Verified && r.Retryable } // UsageStatus is the response from /api/v1/usage.