taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

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.