[taler-docs] branch master updated: docs: add c2ec api extensions

[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 053a2f78 docs: add c2ec api extensions
053a2f78 is described below

commit 053a2f78557287762799970a9ebff1f9df906e34
Author: Joel Häberli <haebu@rubigen.ch>
AuthorDate: Wed Apr 3 19:15:58 2024 +0200

    docs: add c2ec api extensions
---
 core/api-bank-integration.rst | 81 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 79 insertions(+), 2 deletions(-)

diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
index 4131a28a..a4d91f33 100644
--- a/core/api-bank-integration.rst
+++ b/core/api-bank-integration.rst
@@ -152,6 +152,28 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to 
interact with the withdr
       transfer_done: boolean;
     }
 
+  .. ts:def:: IndirectWithdrawalOperationStatus {
+
+    // Since vC2EC
+    interface IndirectWithdrawalOperationStatus {
+
+      // the current status of the withdrawal
+      status: "pending" | "selected" | "aborted" | "confirmed";
+      
+      // the withdrawable amount 
+      amount: Amount;
+
+      // a refund capable payto-uri
+      sender_wire: string;
+
+      // the wire type used for the transaction
+      wire_types: string[];
+
+      // the reserve public key tied to the withdrawal
+      reserve_public_key: EddsaPublicKey;      
+    }
+  }
+
 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
 
   **Request:**
@@ -166,11 +188,29 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to 
interact with the withdr
       selected_exchange: string;
     }
 
+  .. ts:def:: IndirectWithdrawalOperationPostRequest {
+    
+    // Since vC2EC 
+    interface ProviderWithdrawalOperationPostRequest {
+      // Reserve public key.
+      reserve_pub: string;
+
+      // Id of the terminal of a provider. The terminal
+      // is the specific device leveraged for the withdrawal
+      // owned by a specific provider.
+      terminal_id: number;
+    }
+  }
+
   **Response:**
 
   :http:statuscode:`200 OK`:
     The bank has accepted the withdrawal operation parameters chosen by the 
wallet.
     The response is a `BankWithdrawalOperationPostResponse`.
+  :http:statuscode:`204 No Content`:
+    The bank has accepted the withdrawal operation parameters chosen by the 
wallet.
+    This response will be returned in case of a 
`IndirectWithdrawalOperationPostRequest`.
+    Since vC2EC
   :http:statuscode:`404 Not found`:
     The bank does not know about a withdrawal operation with the specified 
``WITHDRAWAL_ID``.
   :http:statuscode:`409 Conflict`:
@@ -198,13 +238,50 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to 
interact with the withdr
       // Only applicable when ``status`` is ``selected`` or ``pending``.
       // It may contain withdrawal operation id
       confirm_transfer_url?: string;
-
-      // Deprecated field use ``status`` instead
       // The transfer has been confirmed and registered by the bank.
       // Does not guarantee that the funds have arrived at the exchange 
already.
       transfer_done: boolean;
     }
 
+.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/payment
+
+  Since protocol vC2EC
+
+  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.
+
+  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;
+    
+    // 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;
+  }
+
+  **Response**
+
+  :http:statuscode:`204 No content`:
+    The payment notification was processed successfully.
+  :http:statuscode:`404 Not found`:
+    The withdrawal operation was not found.
+  :http:statuscode:`409 Conflict`:
+    The withdrawal operation has been aborted previously and can't be aborted
+
+
 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort
 
   Aborts ``WITHDRAWAL_ID`` operation.  Has no effect on an already aborted

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