spec: c2ec api

1 files changed, 47 insertions, 36 deletions

diff --git a/core/api-nonce2ecash.rst b/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.