taler-docs

commit 3a064eb5684feee6796427f2375991606a39cb75
parent f2c4c639af41977b2f9e9eb8074a32a58b0160b8
Author: Antoine A <>
Date:   Sat, 27 Jun 2026 11:01:04 +0200

prepared-transfer: fix doc

Diffstat:
M
core/bank-transfer/post-registration.rst
 | 
96
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------

1 file changed, 88 insertions(+), 8 deletions(-)
diff --git a/core/bank-transfer/post-registration.rst b/core/bank-transfer/post-registration.rst
@@ -3,39 +3,102 @@
 
   Registers a public key for wire transfer use.
 
-  This endpoint generates the appropriate subjects to link a wire transfer 
+  This endpoint generates the appropriate subjects to link a wire transfer
   to a registered public key.
 
   Two public keys must be provided:
   * ``account_pub``: forwarded to the exchange.
   * ``authorization_pub``: encoded inside the transfer subject.
 
-  For non-recurrent transfers, you should use the same key for both ``account_pub`` 
-  and ``authorization_pub``. For recurrent transfers, use a single 
+  For non-recurrent transfers, you should use the same key for both ``account_pub``
+  and ``authorization_pub``. For recurrent transfers, use a single
   ``authorization_pub`` across transfers, but a different ``account_pub`` for each.
 
-  If registered as ``recurrent``, wire adapters will accept incoming transfers 
-  that reuse the same subject. If not marked as recurrent, transfers reusing 
+  If registered as ``recurrent``, wire adapters will accept incoming transfers
+  that reuse the same subject. If not marked as recurrent, transfers reusing
   a subject will bounce.
-  
-  Registering with an existing ``authorization_pub`` will replace the previously 
+
+  Registering with an existing ``authorization_pub`` will replace the previously
   registered information for that key.
-  
+
   **Request:**
 
   .. ts:def:: RegistrationRequest
 
+    interface RegistrationRequest {
+      // Payto URI of the credit account
+      credit_account: Amount;
+
+      // Transfer types
+      type: "reserve" | "kyc";
+
+      // Whether the authorization_pub will be reused for recurrent transfers
+      // Disable bounces in case of authorization_pub reuse
+      recurrent: boolean;
+
+      // Amount to transfer
+      credit_amount: Amount;
+
+      // Public key algorithm
+      alg: "EdDSA";
+
+      // Account public key for the exchange
+      account_pub: EddsaPublicKey;
+
+      // Public key encoded inside the subject
+      authorization_pub: EddsaPublicKey;
+
+      // Signature of the account_pub key using the authorization_pub private key
+      authorization_sig: EddsaSignature;
+    }
+
+  **Response:**
+
+  :http:statuscode:`200 Ok`:
+    Response is a `RegistrationResponse`.
+  :http:statuscode:`400 Bad request`:
+    Input data was invalid.
+  :http:statuscode:`409 Conflict`:
+    * ``TALER_EC_BANK_UNKNOWN_CREDITOR``: credit_account is unknown or not supported.
+    * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the same reserve public key is already registered, you should retry using another key.
+    * ``TALER_EC_BANK_DERIVATION_REUSE``: derived subject is already used, you should retry using another key.
+    * ``TALER_EC_BANK_BAD_SIGNATURE``: signature is invalid.
+
+  **Details:**
+
+  .. ts:def:: TransferSubject
+
+    // Union discriminated by the "type" field.
+    type TransferSubject =
+    | SimpleSubject
+    | UriSubject
+    | SwissQrBillSubject;
+
+  .. ts:def:: SimpleSubject
+
     interface SimpleSubject {
       // Subject for systems accepting large subjects
       type: "SIMPLE";
 
       // Amount to transfer
+      credit_amount: Amount;
+
+      // Encoded string containing either the full key and transfer type or a
+      // derived short subject
+      subject: string;
+    }
+
+  .. ts:def:: UriSubject
 
     interface UriSubject {
       // Subject for systems accepting prepared payments
       type: "URI";
 
       // 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.
       // All necessary information for the user to complete
@@ -45,8 +108,25 @@
       uri: string;
     }
 
+  .. ts:def:: SwissQrBillSubject
+
+    interface SwissQrBillSubject {
+      // Subject for Swiss QR Bill
+      type: "CH_QR_BILL";
+
+      // Amount to transfer
       credit_amount: Amount;
 
       // 27-digit QR Reference number to encode inside a QR-bill
       qr_reference_number: string;
     }
+
+  .. ts:def:: RegistrationResponse
+
+    interface RegistrationResponse {
+      // The transfer subject encoded in all supported formats
+      subjects: TransferSubject[];
+
+      // Expiration date after which this subject is expected to be reused
+      expiration: Timestamp;
+    }