From 10823bcb1bb4a70e2846464359f0d0fa4aec98dc Mon Sep 17 00:00:00 2001 From: admin Date: Thu, 1 Oct 2026 00:44:05 +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. --- src/Qbirr.php | 57 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 45 insertions(+), 12 deletions(-) diff --git a/src/Qbirr.php b/src/Qbirr.php index 6e86537..6f0d2e4 100644 --- a/src/Qbirr.php +++ b/src/Qbirr.php @@ -52,7 +52,11 @@ class Qbirr { * receiver_name: Your receiving account name. * receiver_account: Required for cbe and abyssinia. * } - * @return array { verified: bool, payer: string, amount: float, error: string } + * @return array { + * verified: bool, payer: string, amount: float, error: string, + * paid_amount: float, retryable: bool, code: ?string, + * receiver_source: ?string, sandbox: bool + * } */ public function verify(array $req): array { $body = [ @@ -63,12 +67,46 @@ class Qbirr { ]; if (!empty($req['receiver_account'])) $body['receiver_account'] = $req['receiver_account']; - $data = $this->request('POST', '/api/v1/verify', $body); + return self::normalise($this->request('POST', '/api/v1/verify', $body)); + } + + /** + * Fill in the additive fields so a caller never sees a missing key — including + * against an API build that predates them. + * + * The extra keys and what to do with them: + * + * paid_amount The amount the receipt ACTUALLY shows, in ETB. 0 when + * unreadable. On a short payment compare it to `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. + * code Stable machine-readable reason; branch on this instead of + * parsing `error`. 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). + * null on success. + * receiver_source '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). + * sandbox True only on TEST-... responses. + */ + private static function normalise(array $data): array { return [ - 'verified' => (bool) ($data['verified'] ?? false), - 'payer' => (string) ($data['payer'] ?? ''), - 'amount' => (float) ($data['amount'] ?? 0), - 'error' => (string) ($data['error'] ?? ''), + 'verified' => (bool) ($data['verified'] ?? false), + 'payer' => (string) ($data['payer'] ?? ''), + 'amount' => (float) ($data['amount'] ?? 0), + 'error' => (string) ($data['error'] ?? ''), + 'paid_amount' => (float) ($data['paid_amount'] ?? 0), + 'retryable' => (bool) ($data['retryable'] ?? false), + 'code' => isset($data['code']) ? (string) $data['code'] : null, + 'receiver_source' => isset($data['receiver_source']) ? (string) $data['receiver_source'] : null, + 'sandbox' => (bool) ($data['sandbox'] ?? false), ]; } @@ -138,12 +176,7 @@ class Qbirr { if ($code < 200 || $code >= 300) { throw new QbirrException((string)($data['error'] ?? "HTTP $code"), $code, $data); } - return [ - 'verified' => (bool) ($data['verified'] ?? false), - 'payer' => (string) ($data['payer'] ?? ''), - 'amount' => (float) ($data['amount'] ?? 0), - 'error' => (string) ($data['error'] ?? ''), - ]; + return self::normalise($data); } private function request(string $method, string $path, ?array $body = null): array {