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:
+41
-8
@@ -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 {
|
||||
|
||||
Reference in New Issue
Block a user