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_name: Your receiving account name.
|
||||||
* receiver_account: Required for cbe and abyssinia.
|
* 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 {
|
public function verify(array $req): array {
|
||||||
$body = [
|
$body = [
|
||||||
@@ -63,12 +67,46 @@ class Qbirr {
|
|||||||
];
|
];
|
||||||
if (!empty($req['receiver_account'])) $body['receiver_account'] = $req['receiver_account'];
|
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 [
|
return [
|
||||||
'verified' => (bool) ($data['verified'] ?? false),
|
'verified' => (bool) ($data['verified'] ?? false),
|
||||||
'payer' => (string) ($data['payer'] ?? ''),
|
'payer' => (string) ($data['payer'] ?? ''),
|
||||||
'amount' => (float) ($data['amount'] ?? 0),
|
'amount' => (float) ($data['amount'] ?? 0),
|
||||||
'error' => (string) ($data['error'] ?? ''),
|
'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) {
|
if ($code < 200 || $code >= 300) {
|
||||||
throw new QbirrException((string)($data['error'] ?? "HTTP $code"), $code, $data);
|
throw new QbirrException((string)($data['error'] ?? "HTTP $code"), $code, $data);
|
||||||
}
|
}
|
||||||
return [
|
return self::normalise($data);
|
||||||
'verified' => (bool) ($data['verified'] ?? false),
|
|
||||||
'payer' => (string) ($data['payer'] ?? ''),
|
|
||||||
'amount' => (float) ($data['amount'] ?? 0),
|
|
||||||
'error' => (string) ($data['error'] ?? ''),
|
|
||||||
];
|
|
||||||
}
|
}
|
||||||
|
|
||||||
private function request(string $method, string $path, ?array $body = null): array {
|
private function request(string $method, string $path, ?array $body = null): array {
|
||||||
|
|||||||
Reference in New Issue
Block a user