104-wire-gateway-management-API.rst (10315B)
1 DD 104: Wire Gateway Management API 2 ################################### 3 4 :Design status: Draft 5 :Implementation status: Not started 6 :DD shepherd: Antoine d'Aligny 7 :Historical contributors: Antoine d'Aligny 8 :First published: 2026-09-18 9 :Last substantive change: 2026-11-06 10 11 Summary 12 ======= 13 14 Extend the Wire Gateway API so administrators can inspect raw transactions 15 and follow outgoing operations, including failures. Transfers, bounces and 16 ordinary payments share one operation resource. 17 18 This is a working design document. It describes the new resources and their 19 relationships, detailed protocol specification will follow later. 20 21 Motivation 22 ========== 23 24 Some incoming payments never reach Taler history, and some outgoing payments 25 fail without enough information being available for reconciliation. A bounce 26 may also be skipped or blocked before any outgoing payment exists. 27 28 Listing operations by creation ID is insufficient for monitoring: older 29 operations can change status after newer ones. We need current records and a 30 history of operation statuses. 31 32 Requirements 33 ============ 34 35 * Expose failures, their reasons and the identifiers needed for reconciliation. 36 * Include incomplete transactions and decisions not to bounce. 37 * Share the management model across adapters while keeping their native 38 execution mechanisms and storage models. 39 * Reuse existing Wire Gateway conventions, identifiers and stored fields. 40 41 Proposed Solution 42 ================= 43 44 API placement 45 ------------- 46 47 Add read-only endpoints under ``/management`` in the Wire Gateway API. Reuse 48 its account scope, authentication, types and response conventions. 49 TODO: should we add a new management API with different auth ? 50 51 All lists use the shared :ref:`row-id-pagination` convention. Operation status 52 history also supports the existing :ref:`long-polling` convention. Only the new 53 fields and filters are described below. 54 55 .. list-table:: Proposed endpoints 56 :header-rows: 1 57 :widths: 55 45 58 59 * - Endpoint 60 - Purpose 61 * - ``GET /management/operations`` 62 - List operations, filter by kind or status. 63 * - ``GET /management/operations/$OPERATION_ID`` 64 - Inspect an operation. 65 * - ``GET /management/operations/status-history`` 66 - Follow status and message changes, filter by operation ID. 67 * - ``GET /management/incoming`` 68 - List raw incoming records, filter by kind. 69 * - ``GET /management/incoming/$ROW_ID`` 70 - Inspect an incoming record. 71 * - ``GET /management/outgoing`` 72 - List raw outgoing records. 73 * - ``GET /management/outgoing/$ROW_ID`` 74 - Inspect an outgoing record. 75 76 Operation lists paginate by ``operation_id``, transaction lists and status 77 history paginate by their respective ``row_id``. Status-history IDs are 78 independent of operation IDs. Reuse existing local record IDs where possible. 79 Links to transfers and Taler history use the existing APIs' IDs. 80 81 Incoming and outgoing endpoints expose current records. Tracking later 82 completion or reconciliation requires re-reading these records, their change 83 feeds are deferred. 84 85 Outgoing operations 86 ------------------- 87 88 An operation represents an outgoing intent, even if the adapter implements it 89 as a native chargeback. A bounce stored as an initiated payment appears once. 90 Submission retries retain the same operation ID. 91 92 ``transfer`` originates from the Wire Gateway transfer API. ``bounce`` returns 93 an unsuitable incoming payment. ``payment`` is an ordinary payment initiated 94 through an adapter-specific tool, such as ``libeufin-nexus initiate-payment``. 95 This management API does not create payments. 96 97 A bank payment observed without a local intent belongs in ``outgoing`` and 98 has no operation. 99 100 ``pending``, ``transient_failure``, ``permanent_failure`` and ``success`` 101 follow the existing transfer model. Submission or batch acceptance alone 102 does not mean success: execution must be confirmed. 103 ``late_failure`` records a reversal or failure after success. These management 104 statuses do not change the existing ``/transfers`` response types. 105 106 .. ts:def:: ManagementOperation 107 108 type ManagementOperation = { 109 operation_id: SafeUint64; 110 status: "pending" | "transient_failure" | "permanent_failure" 111 | "success" | "late_failure"; 112 status_msg?: string; 113 114 amount?: Amount; 115 credit_account?: string; 116 subject?: string; 117 118 // Existing link to the reconciled outgoing transaction, when known. 119 outgoing_transaction_id?: SafeUint64; 120 121 // Initiation time 122 created_at: Timestamp; 123 details: { [name: string]: string }; 124 } & ( 125 | { kind: "transfer"; transfer_id: SafeUint64 } 126 | { kind: "bounce"; incoming_transaction_id: SafeUint64 } 127 | { kind: "payment" } 128 ); 129 130 ``kind`` and its associated ID are top-level fields. Transfers require 131 ``transfer_id``, bounces require ``incoming_transaction_id``, and ordinary 132 payments have neither. The two source IDs are mutually exclusive. 133 134 The adapters store one reconciled outgoing transaction per operation. 135 Additional native references can be exposed in ``details``. Status-change 136 times belong to status-history entries, no separate current-status timestamp 137 needs to be maintained. 138 139 Unknown payment fields may be omitted. Available 140 failure explanations are exposed in ``status_msg``. An uncertain outcome, 141 such as a submission timeout, must not be reported as a confirmed rejection. 142 Status alone does not indicate whether submitting again would be safe. 143 144 Reasons and adapter details 145 --------------------------- 146 147 ``status_msg`` exposes the adapter's existing human-readable explanation. 148 On incoming records it explains processing or a decision not to bounce, 149 on operations it explains execution status. Messages are unstructured and 150 clients should not parse them to determine status. 151 152 ``details`` holds adapter-specific information, especially native transaction, 153 submission and batch identifiers needed for manual reconciliation. Native 154 reason codes may be included when available, no common reason-code mapping 155 is required. Generic clients use ``kind`` and operation ``status``. 156 157 Incoming and outgoing records 158 ----------------------------- 159 160 Expose stored transactions even when incomplete or unsuitable for Taler. 161 Common payment fields retain their existing Wire Gateway meanings, unknown 162 values are omitted. Bank documents that cannot be parsed into a transaction 163 remain outside these resources. 164 165 .. ts:def:: ManagementInTx 166 167 interface ManagementInTx { 168 row_id: SafeUint64; 169 date?: Timestamp; 170 amount?: Amount; 171 subject?: string; 172 credit_fee?: Amount; 173 debit_account?: string; 174 175 kind: "incomplete" | "pending" | "rejected" | "reserve" | "kycauth" | "wad"; 176 status_msg?: string; 177 178 // Present once a bounce operation has been initiated. 179 bounce_operation_id?: SafeUint64; 180 taler_history_id?: SafeUint64; 181 details: { [name: string]: string }; 182 } 183 184 ``kind`` is ``incomplete`` when transaction information is missing, ``pending`` 185 when the transaction is complete but awaiting a mapping, or ``rejected`` when 186 the payment cannot be accepted for Taler processing. Available explanations 187 are exposed in ``status_msg``. ``reserve``, ``kycauth`` and ``wad`` identify 188 accepted payments exposed in Taler history, with ``taler_history_id`` linking 189 to the corresponding entry. 190 191 ``bounce_operation_id`` is present if a bounce has been initiated and absent 192 otherwise. Before initiation, the incoming record's ``status_msg`` explains 193 why a return is pending, skipped or blocked. Once initiated, the link remains 194 regardless of the outcome, execution status and reasons belong to the bounce 195 operation. 196 197 .. ts:def:: ManagementOutTx 198 199 interface ManagementOutTx { 200 row_id: SafeUint64; 201 date?: Timestamp; 202 amount?: Amount; 203 subject?: string; 204 debit_fee?: Amount; 205 credit_account?: string; 206 207 operation_id?: SafeUint64; 208 taler_history_id?: SafeUint64; 209 details: { [name: string]: string }; 210 } 211 212 Operation status history 213 ------------------------ 214 215 Record operation creation and changes to ``status`` or ``status_msg`` in a 216 small append-only history. Each entry stores the resulting status and message, 217 clients fetch the operation when they need payment or reconciliation details. 218 Changes to those details alone do not require a history entry. 219 220 .. ts:def:: ManagementStatusChange 221 222 interface ManagementStatusChange { 223 row_id: SafeUint64; 224 operation_id: SafeUint64; 225 status: "pending" | "transient_failure" | "permanent_failure" 226 | "success" | "late_failure"; 227 status_msg?: string; 228 // When the adapter recorded this status, not the bank execution time. 229 timestamp: Timestamp; 230 } 231 232 History starts when the feature is enabled. Existing operations remain 233 available through the current list/detail endpoints without reconstructing 234 past transitions. 235 236 Adapter implementation 237 ---------------------- 238 239 Derive operation ``kind`` by joining the existing transfer and bounce tables, 240 use ``payment`` for other initiated payments. Derive incoming ``kind`` from 241 existing information: a Taler history entry supplies its accepted type, a 242 pending mapping record supplies ``pending``, and missing required transaction 243 information supplies ``incomplete``. A complete record that the adapter has 244 rejected for Taler processing is ``rejected``. 245 246 Magnet and Nexus can reuse initiation IDs as operation IDs, their stored 247 status/message and their existing outgoing link. Map Nexus ``unsubmitted`` to 248 ``pending`` in the API. 249 250 Cyclos keeps its native chargeback path. Its current ``bounced`` table already 251 allows a missing ``chargeback_id``. It can hold the bounce intent before the 252 native call, with status/message fields added for execution tracking and a 253 small ID mapping to expose both bounces and initiated payments as operations. 254 Registration and recovery must update the same intent, including when the 255 chargeback result is initially unknown. 256 257 Reuse stored diagnostic messages and identifiers. Where a skipped or blocked 258 bounce is currently only logged, persist that explanation on the incoming 259 record. Older records may omit unavailable messages. 260 261 Management logic 262 ---------------- 263 264 A separate service can consume status history, notify administrators and keep 265 track of reviewed failures. Adapters remain responsible for execution and 266 reconciliation. Retry and other corrective commands are outside this proposal.