[taler-docs] branch master updated: document new /management/drain endpoint

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 69c1f58  document new /management/drain endpoint
69c1f58 is described below

commit 69c1f58a6b812be832992d261b9eef20e438ea1b
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Fri Jul 29 11:14:03 2022 +0200

    document new /management/drain endpoint
---
 core/api-common.rst   | 15 +++++++++++++++
 core/api-exchange.rst | 48 +++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 62 insertions(+), 1 deletion(-)

diff --git a/core/api-common.rst b/core/api-common.rst
index d170c1d..848d580 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -988,6 +988,21 @@ within the
     uint32_t purse_account_limit;
   };
 
+.. _TALER_MasterDrainProfitPS:
+.. sourcecode:: c
+
+  struct TALER_MasterDrainProfitPS {
+    /**
+     * purpose.purpose = TALER_SIGNATURE_MASTER_DRAIN_PROFITS
+     */
+    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+    struct TALER_WireTransferIdentifierRawP wtid;
+    struct GNUNET_TIME_AbsoluteNBO date;
+    struct TALER_AmountNBO amount;
+    struct GNUNET_HashCode h_section;
+    struct TALER_PaytoHashP h_payto;
+  };
+
 .. _TALER_DepositTrackPS:
 .. sourcecode:: c
 
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 65c3557..0f966f0 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1100,6 +1100,52 @@ Management operations authorized by master key
     }
 
 
+.. http:post:: /management/drain
+
+  This request is used to drain profits from the
+  exchange's escrow account to another regular
+  bank account of the exchange.  The actual drain
+  requires running the ``taler-exchange-drain`` tool.
+
+  **Request:**
+
+  The request must be a `DrainProfitsMessage`.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The profit drain was scheduled.
+  :http:statuscode:`403 Forbidden`:
+    The master signature is invalid.
+
+  **Details:**
+
+  .. ts:def:: DrainProfitsMessage
+
+    interface DrainProfitsMessage {
+
+      // Configuration section of the account to debit.
+      debit_account_section: string;
+
+      // Credit payto URI
+      credit_payto_uri: string;
+
+      // Wire transfer identifier to use.
+      wtid: Base32;
+
+      // Signature by the exchange master key over a
+      // `TALER_MasterDrainProfitPS`.
+      // Must have purpose ``TALER_SIGNATURE_MASTER_DRAIN_PROFITS``.
+      master_sig: EddsaSignature;
+
+      // When was the message created.
+      date: Timestamp;
+
+      // Amount to be drained.
+      amount: Amount;
+
+    }
+
 
 .. http:post:: /management/partners
 
@@ -1500,7 +1546,7 @@ exchange.
       closing_fee: Amount;
 
       // Wire transfer subject.
-      wtid: string;
+      wtid: Base32;
 
       // ``payto://`` URI of the wire account into which the funds were 
returned to.
       receiver_account_details: string;

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