From c6f4e9b3598aedff6d9cce09953f73d49dccee76 Mon Sep 17 00:00:00 2001
From: Marcello Stanisci <ms@taler.net>
Date: Thu, 7 May 2020 15:24:51 +0200
Subject: nexus

Adding endpoints to submit a prepare payment at
the bank and ask for their status.
---
 libeufin/api-nexus2.rst | 121 ++++++++++++++++++++++++++++++++++--------------
 1 file changed, 87 insertions(+), 34 deletions(-)

(limited to 'libeufin')

diff --git a/libeufin/api-nexus2.rst b/libeufin/api-nexus2.rst
index 0802cf07..af940dec 100644
--- a/libeufin/api-nexus2.rst
+++ b/libeufin/api-nexus2.rst
@@ -43,10 +43,10 @@ Bank Account Management
 
 .. http:get:: <nexus>/bank-accounts
   
-  Return the list of bank accounts belonging to the requesting
-  user.
+  **Response:**
 
-  **Response:** A list of `BankAccount` objects.
+  A list of `BankAccount` objects
+  that belong to the requester.
 
   .. ts:def:: BankAccount
      
@@ -61,50 +61,103 @@ Bank Account Management
        holder: string;
      }
 
-.. http:post:: <nexus>/bank-accounts/<my-acct>/prepare-payment
-  
-  Ask nexus to prepare instructions for a new payment.  **The technique
-  to submit prepared payments at the bank is still work in progress!**
-  Note that ``my-acct`` is the bank account that will be **debited**
-  after this operation.
+.. http:post:: <nexus>/bank-accounts/<my-acct>/submit-payment
 
-.. There are (at least) two styles to specify the bank-transport
-.. to use: (1) we specify it here in a field the name of the bank-transport,
-.. or (2) we associate a ID to this prepared payment, and make another
-.. endpoint that accepts the payment's ID and the bank-transport to
-.. use for the submission.  Style (2) seems more flexible.
+  Ask nexus to submit one prepare payment at the bank.
 
   **Request:**
-    .. ts:def:: PreparedPayment
-
-      interface PreparedPayment {
-        // IBAN that will receive the payment.
-        iban: string;
-        // BIC hosting the IBAN.
-        bic: string;
-        // Legal subject that will receive the payment.
-        name: string;
-
-        // amount, in the format CURRENCY:XX.YY
-        amount: string
+
+  .. ts:def:: SubmitPayment
+
+     interface SubmitPayment {
+       // Unique identifier of the (previously) prepared payment
+       // to submit at the bank.
+       uuid: string;
+
+       // Optional field to specify the bank transport to use
+       // for the submission.
+       transport: string;
+     }
+
+  :status 404 Not Found: the unique identifier **or**
+    the bank transport could not be found in the system
+
+
+.. http:get:: <nexus>/bank-accounts/<my-acct>/prepared-payment/$uuid
+   
+   Ask the status of payment ``$uuid``.
+
+   **Response:**
+
+   .. ts:def:: PaymentStatus
+
+      interface PaymentStatus {
+
+        // Payment unique identifier
+        uuid: string;
+
+        // True for submitted payments
+        submitted: boolean;
+
+        // Creditor IBAN
+        creditorIban: string;
+
+        // Creditor BIC
+        creditorBic: string;
+
+        // Creditor legal name
+        creditorName: string;
+
+        // Amount
+        amount: string;
+
+        // Date of submission (in dashed form YYYY-MM-DD)
+        submissionDate: string;
+
+        // Date of preparation (in dashed form YYYY-MM-DD)
+        preparationDate: string;
       }
 
+.. http:post:: <nexus>/bank-accounts/<my-acct>/prepare-payment
+  
+  Ask nexus to prepare instructions for a new payment.
+  Note that ``my-acct`` is the bank account that will be
+  **debited** after this operation.
+
+  **Request:**
+
+  .. ts:def:: PreparedPaymentRequest
+
+     interface PreparedPayment {
+       // IBAN that will receive the payment.
+       iban: string;
+       // BIC hosting the IBAN.
+       bic: string;
+       // Legal subject that will receive the payment.
+       name: string;
+
+       // amount, in the format CURRENCY:XX.YY
+       amount: string
+     }
+
   **Response:**
 
-  **Details:**
+  .. ts:def:: PreparedPaymentResponse
+     
+     interface PreparedPaymentResponse {
+
+       // Opaque identifier to be communicated when
+       // the user wants to submit the payment to the
+       // bank.
+       uuid: string;
+     }
 
 .. http:post:: <nexus>/bank-accounts/<my-acct>/collect-transactions
 
   Ask the default transport to download the latest transactions
-  and store them locally.
+  related to ``my-acct`` and store them locally.
 
   **Request:**
-    The request body is a `CollectTransactions` JSON object.
-    ``my-acct`` is the mnemonic identifier that any bank account
-    stored locally at the nexus has.  Typically, it is the real
-    bank that assigns such identifiers to the bank accounts.
-
-  **Details**
 
   .. ts:def:: CollectTransactions
 
-- 
cgit v1.2.3