Payment search and dashboard

OpenAPI 0.10.0 adds payment history filters and getPaymentDashboard / getPortalPaymentDashboard to the generated PaymentsApi. API keys need payments:read; merchant identity calls need the live membership version. Browser clients call the same-origin BFF and never hold integration credentials.

Search reference is a literal case-insensitive substring of Futa or merchant reference (maximum 100 characters). Optional amount is an exact integer in minor units; combine with currency. state, method (simulator, synthetic-bank or unselected), currency, from and to also combine. Each row carries payer_masked_identifier, the payer’s number as the payment’s detail masks it (+243•••••1234), or null when the payer gave none. Creation dates use inclusive from and exclusive to instants. Paired dates must span at most 366 days. History returns 25 rows and an owned cursor; retain filters while advancing pages. Unknown filters fail validation.

GET /v1/payments/summary accepts the same filters except cursor. Missing date bounds default to now minus 30 days and now. timezone selects Africa/Kinshasa (default) or Africa/Lubumbashi for today’s boundaries; all non-date filters apply to today too. Period and today aggregates share one database snapshot. They describe creation-date cohorts.

approved_volume is a decimal string of minor units: use BigInt or a decimal library, never Number for aggregate arithmetic. USD and CDF are separate. Gross volume includes approved payments even after refunds. From 0.44.0 success_rate_bps is rounded approved over the payments the payer submitted that ended — approved, declined, or expired after submission — × 10,000: an intent that expired before the payer submitted it is not a failure. Null means none of them ended. Pending and uncertain operations do not enter the denominator. terminal and the counts keep their meaning, so the rate is no longer approved / terminal. Each currency and method also counts declined, expired and in_progress (created or awaiting the payer) payments, beside the uncertain and escalated counts; counts may be added across currencies, amounts never.

No full payer phone, account token or checkout capability is exposed. Phone lookup and live settlement forecasting remain separate work. All demonstrated payments are local synthetic fixtures.

CSV/XLSX downloads (0.11.0)

Call exportPayments or exportPortalPayments with required from and to dates and format: "csv" or "xlsx"; generated methods return Blob. Retain the same applied filters as history and omit cursor. The entire matching result is exported from one database query, capped at 5,000 rows. HTTP 413 EXPORT_TOO_LARGE means narrow the filters; no partial file is returned. Live membership/version and payments:read remain required.

Exports include exact amount_minor and currency, UTC creation timestamp, method and references; never sum mixed currencies. CSV uses UTF-8 BOM and quotes, and prefixes potentially executable cells with an apostrophe. XLSX uses text cells to prevent formulas and automatic number conversion. Use XLSX for literal identifiers that CSV readers might coerce. XML-invalid controls are replaced with U+FFFD. Neither format contains payer tokens or checkout capabilities. Responses are private/no-store; browser downloads use the BFF session rather than integration keys.