taler-docs

commit fa579727df1f58159f8a4cfc86768bdf01861ccc
parent 56fba2d9371a47100df42b5cc3e2f0af81166abc
Author: Christian Grothoff <christian@grothoff.org>
Date:   Sun, 21 Jun 2026 16:50:46 +0200

add clarifications and open fixme #11537

Diffstat:
M
core/bank-transfer/post-registration.rst
 | 
31
++++++++++++++++++-------------
M
core/merchant/get-private-accounts-H_WIRE.rst
 | 
8
++++++++
M
core/merchant/get-private-kyc.rst
 | 
1
+

3 files changed, 27 insertions(+), 13 deletions(-)
diff --git a/core/bank-transfer/post-registration.rst b/core/bank-transfer/post-registration.rst
@@ -2,19 +2,19 @@
 
   Register a public key for wire transfer use.
 
-  This endpoint generate appropriate subjects to link a transfer to the   
+  This endpoint generate appropriate subjects to link a transfer to the
   registered public key.
 
-  Two public keys must be provided, the ``account_pub`` key is the key that 
-  will forwarded to the exchange and the ``authorization_pub`` key will be 
+  Two public keys must be provided, the ``account_pub`` key is the key that
+  will forwarded to the exchange and the ``authorization_pub`` key will be
   encoded inside the subject.
 
-  For simple one time wire transfers, use the same key for both ``account_pub`` 
-  and ``authorization_pub``. For recurrent transfers, use a single 
+  For simple one time wire transfers, use the same key for both ``account_pub``
+  and ``authorization_pub``. For recurrent transfers, use a single
   ``authorization_pub`` for different ``account_pub``.
 
-  If registered as ``recurrent`` the wire adapters will keep incoming transfers 
-  reusing the same subject until a registration is performed, else it will 
+  If registered as ``recurrent`` the wire adapters will keep incoming transfers
+  reusing the same subject until a registration is performed, else it will
   bounce.
 
   Registration with the same ``authorization_pu`` will replace the existing information registered for the key.
@@ -26,7 +26,7 @@
     interface RegistrationRequest {
       // Payto URI of the credit account
       credit_account: Amount;
-      
+
       // Transfer types
       type: "reserve" | "kyc";
 
@@ -81,7 +81,7 @@
       // Amount to transfer
       credit_amount: Amount;
 
-      // Encoded string containing either the full key and transfer type or a 
+      // Encoded string containing either the full key and transfer type or a
       // derived short subject
       subject: string;
     }
@@ -89,13 +89,17 @@
   .. ts:def:: UriSubject
 
     interface UriSubject {
-      // Subject for system accepting prepared payments 
+      // Subject for system accepting prepared payments.
       type: "URI";
 
-      // Amount to transfer
+      // Amount to transfer.
+      // FIXME-#11537: C client does not support this field yet.
+      // Is it required? Merchant backend also does not use
+      // it and soly relies on the ``uri``.
       credit_amount: Amount;
 
-      // Prepared payments confirmation URI
+      // Prepared payments confirmation URI.
+      // Should already be a fully constructed payto URI.
       uri: string;
     }
 
@@ -108,7 +112,8 @@
       // Amount to transfer
       credit_amount: Amount;
 
-      // 27-digit QR Reference number
+      // 27-digit QR Reference number.
+      // Stored on payto:// URIs under "ch_qrr".
       qr_reference_number: string;
     }
 
diff --git a/core/merchant/get-private-accounts-H_WIRE.rst b/core/merchant/get-private-accounts-H_WIRE.rst
@@ -2,6 +2,10 @@
 
   This is used to obtain detailed information about a specific bank account.
 
+  Since **v32** this endpoint typically also supports requests
+  with the "Accept" header requesting "text/plain".
+  In this case, an plaintext response suitable for human consumption
+  is returned.
 
   **Required permission:** ``accounts-read``
 
@@ -16,6 +20,10 @@
   :http:statuscode:`404 Not found`:
     The bank account or instance is unknown to the backend.
     Returned with ``TALER_EC_MERCHANT_GENERIC_ACCOUNT_UNKNOWN``.
+  :http:statuscode:`406 Not acceptable`:
+    The merchant backend could not produce a response in the desired format.
+    No error code is returned in this case.
+    Since protocol **v32**.
   :http:statuscode:`500 Internal Server Error`:
     The server experienced an internal failure.
     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
diff --git a/core/merchant/get-private-kyc.rst b/core/merchant/get-private-kyc.rst
@@ -80,6 +80,7 @@
     Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``.
   :http:statuscode:`406 Not acceptable`:
     The merchant backend could not produce a response in the desired format.
+    No error code is returned in this case.
   :http:statuscode:`500 Internal Server Error`:
     The server experienced an internal failure.
     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.