taler-docs

commit 0edd1dd30e8c2e324d173593a16e56cb6ff99fe0
parent 9513fe00000b3d83e9963ccba90f46fb0208151b
Author: Christian Grothoff <christian@grothoff.org>
Date:   Sat, 28 Feb 2026 18:31:51 +0100

spec for #11168

Diffstat:
M
core/api-merchant.rst
 | 
4
----
A
core/merchant/post-private-accounts-H_WIRE-kycauth.rst
 | 
70
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

2 files changed, 70 insertions(+), 4 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -441,16 +441,12 @@ into any of the active bank accounts of an instance.
 
 .. include:: merchant/post-private-accounts.rst
 
-
 .. include:: merchant/patch-private-accounts-H_WIRE.rst
 
-
 .. include:: merchant/get-private-accounts.rst
 
 .. include:: merchant/get-private-accounts-H_WIRE.rst
 
-
-
 .. include:: merchant/delete-private-accounts-H_WIRE.rst
 
 
diff --git a/core/merchant/post-private-accounts-H_WIRE-kycauth.rst b/core/merchant/post-private-accounts-H_WIRE-kycauth.rst
@@ -0,0 +1,70 @@
+.. http:post:: [/instances/$INSTANCE]/private/accounts/$H_WIRE/kycauth
+
+  Request from the backend to create wire transfer instructions for
+  a KYC Auth transfer for a particular bank account and exchange.
+
+  KYC Auth transfers may be required by an exchange when an account is
+  activated for the first time. Furthermore, obtaining the correct
+  wire transfer instructions may require getting details from the
+  exchange and interacting with the banking system to produce a proper
+  (short) wire transfer subject and a transferrable minimum amount.
+  Thus, this endpoint should be used to obtain the wire transfer
+  instructions for a KYC Auth wire transfer when onboarding a new
+  bank account at an exchange that requires proof of control over the
+  bank account via a wire transfer.
+
+  **Required permission:** ``accounts-read``
+
+  **Request:**
+
+   The request must provide `exchange information <KycAuthExchangeSelectionRequest>`.
+
+  **Response:**
+
+  :http:statuscode:`200 Ok`:
+    Wire transfer instructions are returned in the
+    `response <KycAuthWireTransferInstructionResponse>`.
+  :http:statuscode:`404 Not found`:
+    The instance or account are unknown to the exchange.
+
+  **Details:**
+
+  .. ts:def:: KycAuthExchangeSelectionRequest
+
+    interface KycAuthExchangeSelectionRequest {
+
+      // Base URL of the exchange for which KYC Auth wire
+      // transfer instructions are requested.
+      exchange_url: string;
+    }
+
+  .. ts:def:: KycAuthWireTransferInstructionResponse
+
+    interface KycAuthWireTransferInstructionResponse {
+
+      // Array of possible wire transfers to do. There might
+      // be more than one possibility, for example if the
+      // exchange supports multiple bank accounts.
+      wire_instructions: WireTransferInstructionDetail[];
+
+    }
+
+  .. ts:def:: WireTransferInstructionDetail
+
+    interface WireTransferInstructionDetail {
+
+      // Amount to wire (minimum amount, as per ``tiny_amount``
+      // of the ``/keys`` of the exchange).
+      amount: Amount;
+
+      // Full payto:// URL of the (exchange) bank account to which the
+      // money should be sent, excludes the wire subject and the amount.
+      target_payto: string;
+
+      // Subject to use. See also DD80!
+      subject: TransferSubject;
+
+      // Expiration date after which this subject might be reused
+      expiration: Timestamp;
+
+    }