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:02 +03:00
parent f7e858ca20
commit a0dcd4fd23
4 changed files with 143 additions and 21 deletions
+38 -2
View File
@@ -31,10 +31,46 @@ export interface VerifyResult {
verified: boolean;
/** Payer name as extracted from the receipt. */
payer: string;
/** Amount that was actually paid (per the receipt). */
amount: number;
/** Human-readable failure reason, empty on success. */
error: string;
/** The amount you said should have been paid, echoed back. */
amount: number;
/**
* The amount the receipt ACTUALLY shows, in ETB. `0` when unreadable.
* On a short payment compare it to `amount` to see what arrived — the
* human-readable `error` tells you the difference but not the figure.
*/
paid_amount: number;
/**
* TRUE means "we could not reach the bank", so `verified: false` is NOT a
* verdict on the payment — it is "not checked yet".
*
* If this is true, retry or fall back to manual review. Never reject an order
* on it. Check this BEFORE acting on `verified: false`.
*/
retryable: boolean;
/**
* 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` (the only retryable one).
* `null` on success.
*/
code: string | null;
/**
* Which receiver identity was actually checked.
*
* `'settings'` — your saved account in the dashboard (strongest).
* `'request'` — the receiver_name/receiver_account you sent.
* `'none'` — NOTHING was checked. `verified: true` with `'none'` means the
* reference exists and the amount matches, but says nothing
* about who received the money.
*/
receiver_source: 'settings' | 'request' | 'none' | null;
/** Only present on sandbox (`TEST-…`) responses. */
sandbox?: boolean;
}
export interface UsageStatus {
used: number;