fix: api-bank-integration.rst

2 files changed, 17 insertions, 358 deletions

diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
index b5f076ad..c1cb9ae5 100644
--- a/core/api-bank-integration.rst
+++ b/core/api-bank-integration.rst
@@ -152,7 +152,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
       transfer_done: boolean;
     }
 
-  .. ts:def:: IndirectWithdrawalOperationStatus {
+  .. ts:def:: IndirectWithdrawalOperationStatus
 
     // Since vC2EC
     interface IndirectWithdrawalOperationStatus {
@@ -172,7 +172,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
       // the reserve public key tied to the withdrawal
       reserve_public_key: EddsaPublicKey;      
     }
-  }
+  
 
 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
 
@@ -188,7 +188,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
       selected_exchange: string;
     }
 
-  .. ts:def:: IndirectWithdrawalOperationPostRequest {
+  .. ts:def:: IndirectWithdrawalOperationPostRequest
     
     // Since vC2EC 
     interface ProviderWithdrawalOperationPostRequest {
@@ -200,7 +200,6 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
       // owned by a specific provider.
       terminal_id: number;
     }
-  }
 
   **Response:**
 
@@ -250,27 +249,28 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
   Allows a provider to notify the Bank about the payment. This will trigger a payment
   attestation at the provider, which eventually confirms the payment and allows the
   withdrawal. The API is idempotent, meaning sending a payment 
-  notification for the same `WITHDRAWAL_ID` return successfuly but not change anything.
+  notification for the same ``WITHDRAWAL_ID`` return successfuly but not change anything.
 
   Attention: A bank shall **never** just accept the payment directly but instead attest
   the payment using provider specific attestation logic!
 
   **Request:**
   
-  .. ts:def:: PaymentNotification {
-    
-    // The provider specific transaction identifier.
-    // This identifier is used by the bank to attest the 
-    // payment at the providers backend.
-    provider_transaction_id: string;
+  .. ts:def:: PaymentNotification
+
+    interface PaymentNotification {
+      // The provider specific transaction identifier.
+      // This identifier is used by the bank to attest the 
+      // payment at the providers backend.
+      provider_transaction_id: string;
     
-    // The amount to withdraw. Fees are to be sent in the 
-    // separate field 'fees' and not included in the amount.
-    amount Amount;
+      // The amount to withdraw. Fees are to be sent in the 
+      // separate field 'fees' and not included in the amount.
+      amount Amount;
     
-    // The fees, the customer payed at the providers facility.
-    fees: Amount;
-  }
+      // The fees, the customer payed at the providers facility.
+      fees: Amount;
+    }
 
   **Response**
 
diff --git a/core/api-c2ec.rst b/core/api-c2ec.rst
deleted file mode 100644
index c93bbedb..00000000
--- a/core/api-c2ec.rst
+++ /dev/null
@@ -1,341 +0,0 @@
-..
-  This file is part of GNU TALER.
-
-  Copyright (C) 2014-2024 Taler Systems SA
-
-  TALER is free software; you can redistribute it and/or modify it under the
-  terms of the GNU Affero General Public License as published by the Free Software
-  Foundation; either version 2.1, or (at your option) any later version.
-
-  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
-  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
-  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
-
-  You should have received a copy of the GNU Affero General Public License along with
-  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
-
-  @author Joel Häberli
-
-===========================
-The C2EC RESTful API
-===========================
-
-.. note::
-
-  **This API is experimental and not yet implemented**
-
-This chapter describe the APIs that third party providers need to integrate to allow
-withdrawals through indirect payment channels like credit cards or ATM.
-
-.. contents:: Table of Contents
-
---------------
-Authentication
---------------
-
-Terminals which authenticate against the C2EC API must provide their respective
-access token. Therefore they provide a ``Authorization: Bearer $ACCESS_TOKEN`` header,
-where `$ACCESS_TOKEN`` is a secret authentication token configured by the exchange and
-must begin with the RFC 8959 prefix.
-
-----------------------------
-Configuration of C2EC
-----------------------------
-
-.. http:get:: /config
-
-  Return the protocol version and configuration information about the C2EC API.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The exchange responds with a `C2ECConfig` object. This request should
-    virtually always be successful.
-
-  **Details:**
-
-  .. ts:def:: C2ECConfig
-
-    interface C2ECConfig {
-      // Name of the API.
-      name: "taler-c2ec";
-
-      // libtool-style representation of the C2EC protocol version, see
-      // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
-      // The format is "current:revision:age".
-      version: string;
-    }
-
------------------------------
-Withdrawing using C2EC
------------------------------
-
-Withdrawals with a C2EC are based on withdrawal operations which register a withdrawal identifier
-(nonce) at the C2EC component. The provider must first create a unique identifier for the withdrawal
-operation (the ``WOPID``) to interact with the withdrawal operation and eventually withdraw using the wallet.
-
-.. http:post:: /withdrawal-operation
-
-  Register a `WOPID` belonging to a reserve public key.
-
-  **Request:**
-
-  .. ts:def:: C2ECWithdrawRegistration
-
-    interface C2ECWithdrawRegistration {
-      // Maps a nonce generated by the provider to a reserve public key generated by the wallet.
-      wopid: ShortHashCode;
-
-      // Reserve public key generated by the wallet.
-      // According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives)
-      reserve_pub_key: EddsaPublicKey;
-
-      // Optional amount for the withdrawal.
-      amount?: Amount;
-
-      // Id of the terminal of the provider requesting a withdrawal by nonce.
-      // Assigned by the exchange.
-      terminal_id: SafeUint64;
-    }
-
-  **Response:**
-
-  :http:statuscode:`204 No content`:
-    The withdrawal was successfully registered.
-  :http:statuscode:`400 Bad request`:
-    The ``WithdrawRegistration`` request was malformed or contained invalid parameters.
-  :http:statuscode:`500 Internal Server error`:
-    The registration of the withdrawal failed due to server side issues.
-
-.. http:get:: /withdrawal-operation/$WOPID
-
-  Query information about a withdrawal operation, identified by the ``WOPID``.
-
-  **Request:**
-
-  :query long_poll_ms:
-    *Optional.*  If specified, the bank will wait up to ``long_poll_ms``
-    milliseconds for operationt state to be different from ``old_state`` before sending the HTTP
-    response.  A client must never rely on this behavior, as the bank may
-    return a response immediately.
-  :query old_state:
-    *Optional.* Default to "pending".
-
-  **Response:**
-
-  :http:statuscode:`200 Ok`:
-    The withdrawal was found and is returned in the response body as ``C2ECWithdrawalStatus``.
-  :http:statuscode:`404 Not found`:
-    C2EC does not have a withdrawal registered with the specified ``WOPID``.
-
-  **Details**
-
-    .. ts:def:: C2ECWithdrawalStatus
-
-      interface C2ECWithdrawalStatus {
-        // Current status of the operation
-        // pending: the operation is pending parameters selection (exchange and reserve public key)
-        // selected: the operations has been selected and is pending confirmation
-        // aborted: the operation has been aborted
-        // confirmed: the transfer has been confirmed and registered by the bank
-        // Since protocol v1.
-        status: "pending" | "selected" | "aborted" | "confirmed";
-
-        // Amount that will be withdrawn with this operation
-        // (raw amount without fee considerations).
-        amount: Amount;
-
-        // A refund address as ``payto`` URI. This address shall be used
-        // in case a refund must be done. Only not-null if the status
-        // is "confirmed" or "aborted"
-        sender_wire?: string;
-
-        // Reserve public key selected by the exchange,
-        // only non-null if ``status`` is ``selected`` or ``confirmed``.
-        // Since protocol v1.
-        selected_reserve_pub?: string;
-      }
-
-
-.. http:post:: /withdrawal-operation/$WOPID
-
-    Notifies C2EC about an executed payment for a specific withdrawal.
-
-  **Request:**
-
-  .. ts:def:: C2ECPaymentNotification
-
-    interface C2ECPaymentNotification {
-
-      // Unique identifier of the provider transaction.
-      provider_transaction_id: string;
-
-      // Specifies the amount which was payed to the provider (without fees).
-      // This amount shall be put into the reserve linked to by the withdrawal id.
-      amount: Amount;
-
-      // Fees associated with the payment.
-      fees: Amount;
-    }
-
-  **Response:**
-
-  :http:statuscode:`204 No content`:
-    C2EC received the ``C2ECPaymentNotification`` successfully and will further process
-    the withdrawal.
-  :http:statuscode:`400 Bad request`:
-    The ``C2ECPaymentNotification`` request was malformed or contained invalid parameters.
-  :http:statuscode:`404 Not found`:
-    C2EC does not have a withdrawal registered with the specified ``WOPID``.
-  :http:statuscode:`500 Internal Server error`:
-    The ``C2ECPaymentNotification`` could not be processed due to server side issues.
-
-
-------------------
-Taler Wire Gateway
-------------------
-
-C2EC implements the wire gateway API in order to check for incoming transactions and
-let the exchange get proofs of payments. This will allow the C2EC componente to add reserves
-and therefore allow the withdrawal of the money. C2EC does not entirely implement all endpoints,
-because the it is not needed for the case of C2EC. The endpoints not implemented are not described
-further. They will be available but respond with 400 http error code.
-
-.. http:get:: /config
-
-  Return the protocol version and configuration information about the bank.
-  This specification corresponds to ``current`` protocol being version **0**.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The exchange responds with a `WireConfig` object. This request should
-    virtually always be successful.
-
-  **Details:**
-
-  .. ts:def:: WireConfig
-
-    interface WireConfig {
-      // Name of the API.
-      name: "taler-wire-gateway";
-
-      // libtool-style representation of the Bank protocol version, see
-      // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
-      // The format is "current:revision:age".
-      version: string;
-
-      // Currency used by this gateway.
-      currency: string;
-
-      // URN of the implementation (needed to interpret 'revision' in version).
-      // @since v0, may become mandatory in the future.
-      implementation?: string;
-    }
-
-.. http:post:: /transfer
-
-  This API allows the exchange to make a transaction, typically to a merchant.  The bank account
-  of the exchange is not included in the request, but instead derived from the user name in the
-  authentication header and/or the request base URL.
-
-  To make the API idempotent, the client must include a nonce.  Requests with the same nonce
-  are rejected unless the request is the same.
-
-  **Request:**
-
-  .. ts:def:: TransferRequest
-
-    interface TransferRequest {
-      // Nonce to make the request idempotent.  Requests with the same
-      // ``request_uid`` that differ in any of the other fields
-      // are rejected.
-      request_uid: HashCode;
-
-      // Amount to transfer.
-      amount: Amount;
-
-      // Base URL of the exchange.  Shall be included by the bank gateway
-      // in the appropriate section of the wire transfer details.
-      exchange_base_url: string;
-
-      // Wire transfer identifier chosen by the exchange,
-      // used by the merchant to identify the Taler order(s)
-      // associated with this wire transfer.
-      wtid: ShortHashCode;
-
-      // The recipient's account identifier as a payto URI.
-      credit_account: string;
-    }
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The request has been correctly handled, so the funds have been transferred to
-    the recipient's account.  The body is a `TransferResponse`.
-  :http:statuscode:`400 Bad request`:
-    Request malformed. The bank replies with an `ErrorDetail` object.
-  :http:statuscode:`401 Unauthorized`:
-    Authentication failed, likely the credentials are wrong.
-  :http:statuscode:`404 Not found`:
-    The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
-  :http:statuscode:`409 Conflict`:
-    A transaction with the same ``request_uid`` but different transaction details
-    has been submitted before.
-
-  **Details:**
-
-  .. ts:def:: TransferResponse
-
-    interface TransferResponse {
-      // Timestamp that indicates when the wire transfer will be executed.
-      // In cases where the wire transfer gateway is unable to know when
-      // the wire transfer will be executed, the time at which the request
-      // has been received and stored will be returned.
-      // The purpose of this field is for debugging (humans trying to find
-      // the transaction) as well as for taxation (determining which
-      // time period a transaction belongs to).
-      timestamp: Timestamp;
-
-      // Opaque ID of the transaction that the bank has made.
-      row_id: SafeUint64;
-    }
-
-.. http:get:: /history/incoming
-
-  **Request:**
-
-  :query start: *Optional.*
-    Row identifier to explicitly set the *starting point* of the query.
-  :query delta:
-    The *delta* value that determines the range of the query.
-  :query long_poll_ms: *Optional.*  If this parameter is specified and the
-    result of the query would be empty, the bank will wait up to ``long_poll_ms``
-    milliseconds for new transactions that match the query to arrive and only
-    then send the HTTP response.  A client must never rely on this behavior, as
-    the bank may return a response immediately or after waiting only a fraction
-    of ``long_poll_ms``.
-
-  **Response:**
-
-  .. ts:def:: IncomingReserveTransaction
-
-    interface IncomingReserveTransaction {
-      type: "RESERVE";
-
-      // Opaque identifier of the returned record.
-      row_id: SafeUint64;
-
-      // Date of the transaction.
-      date: Timestamp;
-
-      // Amount transferred.
-      amount: Amount;
-
-      // Payto URI to identify the sender of funds.
-      debit_account: string;
-
-      // The reserve public key extracted from the transaction details.
-      reserve_pub: EddsaPublicKey;
-
-    }