[taler-docs] branch master updated: docs: update api spec c2ec

[gnunet]

This is an automated email from the git hooks/post-receive script.

joel-haeberli pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 399f546e docs: update api spec c2ec
399f546e is described below

commit 399f546e1a12b1c6bc72a495eb59c29746c04e49
Author: Joel Häberli <haebu@rubigen.ch>
AuthorDate: Sat Mar 23 12:49:36 2024 +0100

    docs: update api spec c2ec
---
 core/api-c2ec.rst | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 149 insertions(+), 11 deletions(-)

diff --git a/core/api-c2ec.rst b/core/api-c2ec.rst
index 030b961a..297f7317 100644
--- a/core/api-c2ec.rst
+++ b/core/api-c2ec.rst
@@ -72,19 +72,19 @@ 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 ``WITHDRAWAL_ID``) to interact with the withdrawal operation 
and eventually withdraw using the wallet.
+operation (the ``WOPID``) to interact with the withdrawal operation and 
eventually withdraw using the wallet.
 
 .. http:post:: /withdrawal-operation
 
-  Initiate the withdrawal operation, identified by the ``WITHDRAWAL_ID``.
+  Register a `WOPID` belonging to a reserve public key. 
 
   **Request:**
 
-  .. ts:def:: C2ECWithdrawalOperationPostRequest
+  .. ts:def:: C2ECWithdrawRegistration
 
-    interface WithdrawRegistration {
+    interface C2ECWithdrawRegistration {
       // Maps a nonce generated by the provider to a reserve public key 
generated by the wallet.
-      withdrawal_id: ShortHashCode;
+      wopid: ShortHashCode;
 
       // Reserve public key generated by the wallet.
       // According to TALER_ReservePublicKeyP 
(https://docs.taler.net/core/api-common.html#cryptographic-primitives)
@@ -107,16 +107,16 @@ operation (the ``WITHDRAWAL_ID``) to interact with the 
withdrawal operation and
   :http:statuscode:`500 Internal Server error`:
     The registration of the withdrawal failed due to server side issues.
 
-.. http:get:: /withdrawal-operation/$WITHDRAWAL_ID
+.. http:get:: /withdrawal-operation/$WOPID
 
-  Query information about a withdrawal operation, identified by the 
``WITHDRAWAL_ID``.
+  Query information about a withdrawal operation, identified by the ``WOPID``.
 
   **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 
``WITHDRAWAL_ID``.
+    C2EC does not have a withdrawal registered with the specified ``WOPID``.
 
   **Details**
 
@@ -138,7 +138,7 @@ operation (the ``WITHDRAWAL_ID``) to interact with the 
withdrawal operation and
         // 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"
-        refund_wire?: string;
+        sender_wire?: string;
 
         // Reserve public key selected by the exchange,
         // only non-null if ``status`` is ``selected`` or ``confirmed``.
@@ -147,7 +147,7 @@ operation (the ``WITHDRAWAL_ID``) to interact with the 
withdrawal operation and
       }
 
 
-.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
+.. http:post:: /withdrawal-operation/$WOPID
 
     Notifies C2EC about an executed payment for a specific withdrawal.
 
@@ -176,6 +176,144 @@ operation (the ``WITHDRAWAL_ID``) to interact with the 
withdrawal operation and
   :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 
``WITHDRAWAL_ID``.
+    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 418 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:post:: /history/incoming
+
+  **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;
+
+    }
+

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.