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.
This commit is contained in:
2026-10-01 00:44:05 +03:00
parent 99f27b607d
commit 10823bcb1b
+41 -8
View File
@@ -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'] ?? ''),
'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 {