commit af8509b6b619fd51abc4f790336b14195d00b278
parent e606f5d4612081256597dddc7ae8aec9207790e4
Author: Antoine A <>
Date: Wed, 24 Jun 2026 13:20:07 +0200
prepared-transfer: improve doc
Diffstat:
1 file changed, 24 insertions(+), 100 deletions(-)
diff --git a/core/bank-transfer/post-registration.rst b/core/bank-transfer/post-registration.rst
@@ -1,128 +1,52 @@
-.. http:post:: /registration
-
- Register a public key for wire transfer use.
- This endpoint generate appropriate subjects to link a transfer to the
- registered public key.
+.. http:post:: /registration
- 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.
+ Registers a public key for wire transfer use.
- 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``.
+ This endpoint generates the appropriate subjects to link a wire transfer
+ to a registered public key.
- If registered as ``recurrent`` the wire adapters will keep incoming transfers
- reusing the same subject until a registration is performed, else it will
- bounce.
+ Two public keys must be provided:
+ * ``account_pub``: forwarded to the exchange.
+ * ``authorization_pub``: encoded inside the transfer subject.
- Registration with the same ``authorization_pu`` will replace the existing information registered for the key.
+ 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
+ a subject will bounce.
+
+ 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 system accepting large subjects
+ // 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 system accepting prepared payments.
+ // 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.
- // Should already be a fully constructed payto URI.
+ // All necessary information for the user to complete
+ // the transfer is encoded inside the URI.
+ // Clients should not try to decode the URI but should
+ // let the system handle it.
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.
- // Stored on payto:// URIs under "ch_qrr".
+ // 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;
- }
