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

[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 54a3a6b1 spec: c2ec api
54a3a6b1 is described below

commit 54a3a6b1f0f83e1096d7a069e7a4d9b723a50bd8
Author: Joel Häberli <haebu@rubigen.ch>
AuthorDate: Wed Mar 20 22:12:04 2024 +0100

    spec: c2ec api
---
 core/{api-nonce2ecash.rst => api-c2ec.rst} | 83 +++++++++++++++++-------------
 1 file changed, 47 insertions(+), 36 deletions(-)

diff --git a/core/api-nonce2ecash.rst b/core/api-c2ec.rst
similarity index 62%
rename from core/api-nonce2ecash.rst
rename to core/api-c2ec.rst
index ad7c4997..030b961a 100644
--- a/core/api-nonce2ecash.rst
+++ b/core/api-c2ec.rst
@@ -17,7 +17,7 @@
   @author Joel Häberli
 
 ===========================
-The nonce2ecash RESTful API
+The C2EC RESTful API
 ===========================
 
 .. note::
@@ -33,45 +33,45 @@ withdrawals through indirect payment channels like credit 
cards or ATM.
 Authentication
 --------------
 
-Terminals which authenticate against the nonce2ecash API must provide their 
respective 
+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 nonce2ecash
+Configuration of C2EC
 ----------------------------
 
 .. http:get:: /config
 
-  Return the protocol version and configuration information about the 
nonce2ecash API.
+  Return the protocol version and configuration information about the C2EC API.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The exchange responds with a `Nonce2ecashConfig` object. This request 
should
+    The exchange responds with a `C2ECConfig` object. This request should
     virtually always be successful.
 
   **Details:**
 
-  .. ts:def:: Nonce2ecashConfig
+  .. ts:def:: C2ECConfig
 
-    interface Nonce2ecashConfig {
+    interface C2ECConfig {
       // Name of the API.
-      name: "taler-nonce2ecash";
+      name: "taler-c2ec";
 
-      // libtool-style representation of the nonce2ecash protocol version, see
+      // 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 nonce2ecash
+Withdrawing using C2EC
 -----------------------------
 
-Withdrawals with a nonce2ecash are based on withdrawal operations which 
register a withdrawal identifier
-(nonce) at the nonce2ecash component. The provider must first create a unique 
identifier for the withdrawal 
+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.
 
 .. http:post:: /withdrawal-operation
@@ -80,7 +80,7 @@ operation (the ``WITHDRAWAL_ID``) to interact with the 
withdrawal operation and
 
   **Request:**
 
-  .. ts:def:: WithdrawRegistration
+  .. ts:def:: C2ECWithdrawalOperationPostRequest
 
     interface WithdrawRegistration {
       // Maps a nonce generated by the provider to a reserve public key 
generated by the wallet.
@@ -114,37 +114,48 @@ operation (the ``WITHDRAWAL_ID``) to interact with the 
withdrawal operation and
   **Response:**
 
   :http:statuscode:`200 Ok`:
-    The withdrawal was found and is returned in the response body as 
``Withdrawal``.
+    The withdrawal was found and is returned in the response body as 
``C2ECWithdrawalStatus``.
   :http:statuscode:`404 Not found`:
-    nonce2ecash does not have a withdrawal registered with the specified 
``WITHDRAWAL_ID``.
+    C2EC does not have a withdrawal registered with the specified 
``WITHDRAWAL_ID``.
 
   **Details**
 
-    .. ts:def:: Withdrawal
-
-      interface Withdrawal {
-
-        // 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;
-
-        // Status of the withdrawal
-        //  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
-        withdrawal_status: EddsaPublicKey;
+    .. 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"
+        refund_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/$WITHDRAWAL_ID
 
-    Notifies nonce2ecash about an executed payment for a specific withdrawal.
+    Notifies C2EC about an executed payment for a specific withdrawal.
 
   **Request:**
 
-  .. ts:def:: PaymentNotification
+  .. ts:def:: C2ECPaymentNotification
 
-    interface PaymentNotification {
+    interface C2ECPaymentNotification {
 
       // Unique identifier of the provider transaction.
       provider_transaction_id: string;
@@ -160,11 +171,11 @@ operation (the ``WITHDRAWAL_ID``) to interact with the 
withdrawal operation and
   **Response:**
 
   :http:statuscode:`204 No content`:
-    nonce2ecash received the ``PaymentNotification`` successfully and will 
further process
+    C2EC received the ``C2ECPaymentNotification`` successfully and will 
further process
     the withdrawal.
   :http:statuscode:`400 Bad request`:
-    The ``PaymentNotification`` request was malformed or contained invalid 
parameters.
+    The ``C2ECPaymentNotification`` request was malformed or contained invalid 
parameters.
   :http:statuscode:`404 Not found`:
-    nonce2ecash does not have a withdrawal registered with the specified 
``WITHDRAWAL_ID``.
+    C2EC does not have a withdrawal registered with the specified 
``WITHDRAWAL_ID``.
   :http:statuscode:`500 Internal Server error`:
-    The ``PaymentNotification`` could not be processed due to server side 
issues.
+    The ``C2ECPaymentNotification`` could not be processed due to server side 
issues.

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