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 {