commit 5e64178ee5577fa490350d0c9e5d903587ac4ac4
parent c0f2a515fcaba94e1e171216edcb6294e4b257bd
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 5 Nov 2024 10:32:51 +0100
clarify normalized vs. full payto URIs
Diffstat:
7 files changed, 131 insertions(+), 94 deletions(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
@@ -1723,7 +1723,7 @@ the **taler-exchange-closer** component is operating correctly.
// The wire transfer identifier
wtid : HashCode;
- // payto URI (RFC 8905) of the account that
+ // Full payto:// URI (RFC 8905) of the account that
// should have been credited.
account : string;
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
@@ -140,8 +140,8 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
// @since **v4**
card_fees?: Amount;
- // Bank account of the customer that is debiting, as an
- // RFC 8905 ``payto`` URI.
+ // Bank account of the customer that is debiting, as a
+ // full RFC 8905 ``payto`` URI.
sender_wire?: string;
// Base URL of the suggested exchange. The bank may have
@@ -206,7 +206,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
// subject to fund the withdrawal.
reserve_pub: EddsaPublicKey;
- // RFC 8905 (payto) address of the exchange account to be
+ // Full RFC 8905 (payto) address of the exchange account to be
// credited for the withdrawal.
selected_exchange: string;
diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst
@@ -103,7 +103,7 @@ Making Transactions
// associated with this wire transfer.
wtid: ShortHashCode;
- // The recipient's account identifier as a payto URI.
+ // The recipient's account identifier as a full payto URI.
credit_account: string;
}
@@ -183,7 +183,7 @@ Making Transactions
// Array of initiated transfers.
transfers: TransferListStatus[];
- // Payto URI to identify the sender of funds.
+ // Full payto:// URI to identify the sender of funds.
// This must be one of the exchange's bank accounts.
// Credit account is shared by all incoming transactions
// as per the nature of the request.
@@ -207,7 +207,7 @@ Making Transactions
// Amount to transfer.
amount: Amount;
- // The recipient's account identifier as a payto URI.
+ // The recipient's account identifier as a full payto:// URI.
credit_account: string;
// Timestamp that indicates when the wire transfer was executed.
@@ -265,7 +265,7 @@ Making Transactions
// associated with this wire transfer.
wtid: ShortHashCode;
- // The recipient's account identifier as a payto URI.
+ // The recipient's account identifier as a full payto URI.
credit_account: string;
// Timestamp that indicates when the wire transfer was executed.
@@ -331,7 +331,7 @@ accounts are merged into a single history.
// Array of incoming transactions.
incoming_transactions: IncomingBankTransaction[];
- // Payto URI to identify the receiver of funds.
+ // Full payto URI to identify the receiver of funds.
// This must be one of the exchange's bank accounts.
// Credit account is shared by all incoming transactions
// as per the nature of the request.
@@ -361,7 +361,7 @@ accounts are merged into a single history.
// Amount transferred.
amount: Amount;
- // Payto URI to identify the sender of funds.
+ // Full payto URI to identify the sender of funds.
debit_account: string;
// The account public key extracted from the transaction details.
@@ -382,7 +382,7 @@ accounts are merged into a single history.
// Amount transferred.
amount: Amount;
- // Payto URI to identify the sender of funds.
+ // Full payto URI to identify the sender of funds.
debit_account: string;
// The reserve public key extracted from the transaction details.
@@ -403,7 +403,7 @@ accounts are merged into a single history.
// Amount transferred.
amount: Amount;
- // Payto URI to identify the sender of funds.
+ // Full payto URI to identify the sender of funds.
debit_account: string;
// Base URL of the exchange that originated the wad.
@@ -454,7 +454,7 @@ accounts are merged into a single history.
// Array of outgoing transactions.
outgoing_transactions: OutgoingBankTransaction[];
- // Payto URI to identify the sender of funds.
+ // Full payto URI to identify the sender of funds.
// This must be one of the exchange's bank accounts.
// Credit account is shared by all incoming transactions
// as per the nature of the request.
@@ -473,7 +473,7 @@ accounts are merged into a single history.
// Amount transferred.
amount: Amount;
- // Payto URI to identify the receiver of funds.
+ // Full payto URI to identify the receiver of funds.
credit_account: string;
// The wire transfer ID in the outgoing transaction.
@@ -510,7 +510,7 @@ exposed by bank gateways in production.
// to identify the reserve that is being topped up.
reserve_pub: EddsaPublicKey;
- // Account (as payto URI) that makes the wire transfer to the exchange.
+ // Account (as full payto URI) that makes the wire transfer to the exchange.
// Usually this account must be created by the test harness before this
// API is used. An exception is the "fakebank", where any debit account
// can be specified, as it is automatically created.
@@ -571,7 +571,7 @@ exposed by bank gateways in production.
// to associate this key with the originating bank account.
account_pub: EddsaPublicKey;
- // Account (as payto URI) that makes the wire transfer to the exchange.
+ // Account (as full payto URI) that makes the wire transfer to the exchange.
// Usually this account must be created by the test harness before this
// API is used. An exception is the "fakebank", where any debit account
// can be specified, as it is automatically created.
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -275,6 +275,34 @@ Common encodings
This section describes how certain types of values are represented throughout the API.
+.. _payto:
+
+
+Payto URIs:
+^^^^^^^^^^^
+
+RFC 8905 defines payto://-URIs which GNU Taler uses to identify bank
+accounts. In GNU Taler, we primarily distinguish three types of
+payto://-URIs:
+
+* First, a **normalized** payto-URI uniquely identifies a bank account (or
+ wallet) and must be able to serve as a canonical representation of such a
+ bank account. Thus, optional arguments such as the *receiver-name* or
+ optional path components such as the BIC must be removed and the account
+ must be given in a canonical form for the wire method (for example,
+ everything in lower-case).
+
+* Second, a **full** payto-URI is not expected to have a canonical form for
+ a bank account (there can be many full payto-URIs for the same bank
+ account) and must include at least the *receiver-name* but possibly also
+ other (in RFC 8905 optional) arguments to identify the recipient, as
+ those may be needed to do a wire transfer.
+
+* On occation, we also use full payto://-URIs that additionally specify the
+ *amount* and wire transfer *subject* and are actually intended to trigger
+ a wire transfer.
+
+
.. _base32:
Binary Data
@@ -853,7 +881,7 @@ body.
// is required.
// The account holder can uses the ``/kyc-check/$H_PAYTO``
// endpoint to check the KYC status or initiate the KYC process.
- h_payto: PaytoHash;
+ h_payto: NormalizedPaytoHash;
// Public key associated with the account. The client must sign
// the initial request for the KYC status using the corresponding
@@ -923,10 +951,21 @@ uses 512-bit hash codes (64 bytes).
struct GNUNET_HashCode hash;
};
-.. _PaytoHash:
+.. _FullPaytoHash:
.. sourcecode:: c
- struct TALER_PaytoHash {
+ struct TALER_FullPaytoHash {
+ // Hash over a full payto://-URI, including receiver-name
+ // (and possibly BIC and other optional fields).
+ struct GNUNET_ShortHashCode hash;
+ };
+
+.. _NormalizedPaytoHash:
+.. sourcecode:: c
+
+ struct TALER_NormalizedPaytoHash {
+ // Hash over a normalized payto://-URI, including all optional
+ // fields and also with account-part canonicalized (so no BIC).
struct GNUNET_ShortHashCode hash;
};
@@ -1316,7 +1355,7 @@ within the
* purpose.purpose = TALER_SIGNATURE_MASTER_WIRE_DETAILS
*/
struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
- struct TALER_PaytoHash h_wire_details;
+ struct TALER_FullPaytoHash h_wire_details;
struct GNUNET_HashCode h_conversion_url;
struct GNUNET_HashCode h_credit_restrictions;
struct GNUNET_HashCode h_debit_restrictions;
@@ -1369,7 +1408,7 @@ within the
struct GNUNET_TIME_AbsoluteNBO date;
struct TALER_AmountNBO amount;
struct GNUNET_HashCode h_section;
- struct TALER_PaytoHashP h_payto;
+ struct TALER_FullPaytoHashP h_payto;
};
.. _TALER_DepositTrackPS:
@@ -1611,7 +1650,7 @@ within the
struct GNUNET_TIME_AbsoluteNBO timestamp;
struct TALER_AmountNBO closing_amount;
struct TALER_ReservePublicKeyP reserve_pub;
- struct TALER_PaytoHash h_wire;
+ struct TALER_FullPaytoHash h_wire;
};
.. _TALER_CoinLinkSignaturePS:
@@ -1768,7 +1807,7 @@ within the
*/
struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
struct GNUNET_TIME_AbsoluteNBO merge_timestamp;
- struct TALER_PaytoHashP h_wire;
+ struct TALER_NormalizedPaytoHashP h_wire;
};
@@ -1800,20 +1839,6 @@ within the
struct TALER_AmountNBO threshold;
};
-.. _TALER_AccountSetupSuccessSignaturePS:
-.. sourcecode:: c
-
- struct TALER_AccountSetupSuccessSignaturePS {
- /**
- * purpose.purpose = TALER_SIGNATURE_WALLET_ACCOUNT_SETUP_SUCCESS
- */
- struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
- struct TALER_PaytoHash h_payto;
- struct GNUNET_HashCode h_kyc;
- struct GNUNET_TIME_AbsoluteNBO timestamp;
- };
-
-
.. _TALER_PurseMergeSuccessSignaturePS:
.. sourcecode:: c
@@ -1827,7 +1852,7 @@ within the
struct TALER_AmountNBO merge_amount_after_fees;
struct GNUNET_TIME_AbsoluteNBO contract_time;
struct TALER_PrivateContractHashP h_contract_terms;
- struct TALER_PaytoHashP h_wire;
+ struct TALER_NormalizedPaytoHashP h_wire;
uint32_t min_age;
};
@@ -1984,7 +2009,7 @@ within the
*/
struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
struct GNUNET_TIME_AbsoluteNBO start_date;
- struct TALER_PaytoHash h_wire;
+ struct TALER_FullPaytoHash h_wire;
struct GNUNET_HashCode h_conversion_url;
struct GNUNET_HashCode h_credit_restrictions;
struct GNUNET_HashCode h_debit_restrictions;
@@ -1999,7 +2024,7 @@ within the
*/
struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
struct GNUNET_TIME_AbsoluteNBO end_date;
- struct TALER_PaytoHash h_wire;
+ struct TALER_FullPaytoHash h_wire;
};
@@ -2028,7 +2053,7 @@ within the
struct GNUNET_HashCode h_justification GNUNET_PACKED;
struct GNUNET_TIME_TimestampNBO decision_time;
struct TALER_AmountNBO new_threshold;
- struct TALER_PaytoHashP h_payto GNUNET_PACKED;
+ struct TALER_NormalizedPaytoHashP h_payto GNUNET_PACKED;
struct GNUNET_HashCode h_kyc_requirements;
uint32_t new_state GNUNET_PACKED;
};
@@ -2072,7 +2097,7 @@ within the
*/
struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
struct GNUNET_TIME_TimestampNBO request_timestamp;
- struct TALER_PaytoHashP target_account_h_payto;
+ struct TALER_FullPaytoHashP target_account_h_payto;
};
.. _TALER_WalletReserveAttestRequestSignaturePS:
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -286,7 +286,7 @@ Account Management
// Addresses where to send the TAN for protected operations.
contact_data?: ChallengeContactData;
- // IBAN 'payto' URI of a fiat bank account with a 'receiver-name' parameter.
+ // Full 'payto' URI of a fiat bank account with a 'receiver-name' parameter.
// If 'receiver-name' is missing, ``name`` will be used instead.
// Payments will be sent to this bank account
// when the user wants to convert the regional currency
@@ -369,7 +369,7 @@ Account Management
// Addresses where to send the TAN for protected operations.
contact_data?: ChallengeContactData;
- // IBAN 'payto' URI of a fiat bank account with a 'receiver-name' parameter.
+ // Full 'payto' URI of a fiat bank account with a 'receiver-name' parameter.
// If 'receiver-name' is missing, ``name`` will be used instead.
// Payments will be sent to this bank account
// when the user wants to convert the regional currency
@@ -485,7 +485,7 @@ Account Management
:query limit: *Optional.*
At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since protocol v5.
- :query offset: *Optional.*
+ :query offset: *Optional.*
Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v5.
:query filter_name: *Optional.*
Pattern to filter on the account's legal name. Given
@@ -543,7 +543,7 @@ Account Management
:query limit: *Optional.*
At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since protocol v5.
- :query offset: *Optional.*
+ :query offset: *Optional.*
Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v5.
:query filter_name: *Optional.*
Pattern to filter on the account's legal name. Given
@@ -668,7 +668,7 @@ Account Management
// as well.
contact_data?: ChallengeContactData;
- // IBAN 'payto' URI with a 'receiver-name' parameter of a fiat bank
+ // Full 'payto' URI (with a 'receiver-name' parameter) of a fiat bank
// account where to send cashouts. This field is optional
// because not all the accounts are required to participate
// in the merchants' circuit. One example is the exchange:
@@ -705,7 +705,7 @@ Transactions
:query limit: *Optional.*
At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since protocol v5.
- :query offset: *Optional.*
+ :query offset: *Optional.*
Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v5.
:query timeout_ms: *Optional.*
Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for at least one element to be shown. Only useful if *limit* is positive. Since protocol v5.
@@ -753,17 +753,25 @@ Transactions
.. ts:def:: BankAccountTransactionInfo
interface BankAccountTransactionInfo {
+ // ???
creditor_payto_uri: string;
+ // ???
debtor_payto_uri: string;
+ // ???
amount: Amount;
+
+ // ???
direction: "debit" | "credit";
+ // ???
subject: string;
// Transaction unique ID. Matches
// $TRANSACTION_ID from the URI.
row_id: Integer;
+
+ // ???
date: Timestamp;
}
@@ -776,7 +784,7 @@ Transactions
.. ts:def:: CreateTransactionRequest
interface CreateTransactionRequest {
- // Address in the Payto format of the wire transfer receiver.
+ // Address in the payto format of the wire transfer receiver.
// It needs at least the 'message' query string parameter.
payto_uri: string;
@@ -921,7 +929,7 @@ Account withdrawals
serves as an authenticator.
**Request:**
-
+
:query old_state:
*Optional.* Defaults to "pending".
:query timeout_ms: *Optional.*
@@ -1096,7 +1104,7 @@ Cashouts
:query limit: *Optional.*
At most return the given number of results. Negative for descending by ``cashout_id``, positive for ascending by ``cashout_id``. Defaults to ``-20``. Since protocol **v5**.
- :query offset: *Optional.*
+ :query offset: *Optional.*
Starting ``cashout_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v5.
:query delta: *Optional.*
Deprecated in protocol v5. Use *limit* instead.
@@ -1137,7 +1145,7 @@ Cashouts
:query limit: *Optional.*
At most return the given number of results. Negative for descending by ``cashout_id``, positive for ascending by ``cashout_id``. Defaults to ``-20``. Since protocol v5.
- :query offset: *Optional.*
+ :query offset: *Optional.*
Starting ``cashout_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v5.
:query delta: *Optional.*
Deprecated in protocol v5. Use *limit* instead.
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -289,7 +289,7 @@ possibly by using HTTPS.
.. ts:def:: WireAccount
interface WireAccount {
- // ``payto://`` URI identifying the account and wire method
+ // Full ``payto://`` URI identifying the account and wire method
payto_uri: string;
// URI to convert amounts from or to the currency used by
@@ -342,7 +342,7 @@ possibly by using HTTPS.
.. ts:def:: RegexAccountRestriction
// Accounts interacting with this type of account
- // restriction must have a payto://-URI matching
+ // restriction must have a normalized payto://-URI matching
// the given regex.
interface RegexAccountRestriction {
@@ -1167,7 +1167,7 @@ Management operations authorized by master key
interface WireSetupMessage {
- // ``payto://`` URL identifying the account and wire method
+ // Full ``payto://`` URL identifying the account and wire method
payto_uri: string;
// Signature using the exchange's offline key
@@ -1230,7 +1230,7 @@ Management operations authorized by master key
interface WireTeardownMessage {
- // ``payto://`` URL identifying the account and wire method
+ // Full ``payto://`` URL identifying the account and wire method
payto_uri: string;
// Signature using the exchange's offline key over a
@@ -1275,7 +1275,7 @@ Management operations authorized by master key
// Configuration section of the account to debit.
debit_account_section: string;
- // Credit payto URI
+ // Full payto URI of the account to credit.
credit_payto_uri: string;
// Wire transfer identifier to use.
@@ -2154,7 +2154,7 @@ Reserve History
// Amount deposited.
amount: Amount;
- // Sender account ``payto://`` URL.
+ // Sender account full payto:// URI.
sender_account_url: string;
// Opaque identifier internal to the exchange that
@@ -2185,7 +2185,7 @@ Reserve History
// Wire transfer subject.
wtid: Base32;
- // ``payto://`` URI of the wire account into which the funds were returned to.
+ // Full payto URI of the wire account into which the funds were returned to.
receiver_account_details: string;
// This is a signature over a
@@ -2245,8 +2245,8 @@ Reserve History
// ``TALER_SIGNATURE_WALLET_RESERVE_CLOSE``.
reserve_sig: EddsaSignature;
- // Target account ``payto://``, optional.
- h_payto?: PaytoHash;
+ // Hash over the full payto URI of the target account.
+ h_payto?: FullPaytoHash;
// Timestamp of the close request.
request_timestamp: Timestamp;
@@ -2797,7 +2797,7 @@ proof to the seller for the escrow of sufficient fund.
interface BatchDepositRequest {
- // The merchant's account details.
+ // The merchant's account details as a full payto URI.
merchant_payto_uri: string;
// The salt is used to hide the ``payto_uri`` from customers
@@ -2996,7 +2996,7 @@ proof to the seller for the escrow of sufficient fund.
// The public key of the seller.
pubkey: EddsaPublicKey;
- // The seller's account details.
+ // The seller's account details as a full payto URI.
payto_uri: string;
}
@@ -3688,7 +3688,7 @@ typically also view the balance.)
merchant_pub: EddsaPublicKey;
// Hash of the payto:// account URI (identical for all deposits).
- h_payto: PaytoHash;
+ h_payto: FullPaytoHash;
// Time of the execution of the wire transfer by the exchange.
execution_time: Timestamp;
@@ -4294,7 +4294,7 @@ Wallet-to-wallet transfers
interface MergeRequest {
- // payto://-URI of the account the purse is to be merged into.
+ // Normalized payto URI of the account the purse is to be merged into.
// Must be of the form: 'payto://taler/$EXCHANGE_URL/$RESERVE_PUB'.
payto_uri: string;
@@ -4645,7 +4645,7 @@ wallet-to-wallet payments. Only another exchange should access this endpoint.
// Amount in the purse.
amount: Amount;
- // payto://-URI of the account the purse is to be merged into.
+ // Normalized payto URI of the account the purse is to be merged into.
// Must be of the form: 'payto://taler/EXCHANGE_URL/RESERVE_PUB'.
payto_uri: string;
@@ -4768,7 +4768,7 @@ regulatory compliance.
}
-.. http:get:: /kyc-check/$H_PAYTO
+.. http:get:: /kyc-check/$H_NORMALIZED_PAYTO
Checks the KYC status of a particular payment target and possibly begins a
KYC process by allowing the customer to choose the next KYC measure to
@@ -4779,7 +4779,7 @@ regulatory compliance.
statisfied and the operation can now proceed). Long-polling may be used
to instantly observe a change in the KYC requirement status.
- Given a valid pair of payto hash and account owner signature, the
+ Given a valid pair of a normalized payto hash and account owner signature, the
``/kyc-check/`` endpoint returns either just the KYC status or redirects the
client (202) to the next required stage of the KYC process. The redirection
must be for an HTTP(S) endpoint to be triggered via a simple HTTP GET. It
@@ -4837,7 +4837,7 @@ regulatory compliance.
:http:statuscode:`403 Forbidden`:
The provided signature is not acceptable for the given account. The response will be an `KycCheckAccountExpectedResponse` object which specifies the expected account public key.
:http:statuscode:`404 Not found`:
- The account identified by the payto hash is unknown.
+ The account identified by the normalized payto hash is unknown.
:http:statuscode:`409 Conflict`:
The bank account is not (yet) associated with a public key. The account owner must do a wire transfer to the exchange with the account public key in the wire transfer subject to enable authentication.
@@ -5071,11 +5071,11 @@ regulatory compliance.
is also the place where we could integrate the payment process for the KYC fee
in the future (since **vATTEST**).
-.. http:get:: /kyc-proof/$PROVIDER_NAME?state=$H_PAYTO
+.. http:get:: /kyc-proof/$PROVIDER_NAME?state=$H_NORMALIZED_PAYTO
Upon completion of the process at the external KYC provider, the provider
must redirect the client (browser) to trigger a GET request to a new
- ``/kyc-proof/$H_PAYTO/$PROVIDER_NAME`` endpoint. Once this endpoint is
+ ``/kyc-proof/$H_NORMALIZED_PAYTO/$PROVIDER_NAME`` endpoint. Once this endpoint is
triggered, the exchange will pass the received arguments to the respective
logic plugin. The logic plugin will then (asynchronously) update the KYC
status of the user. The logic plugin should redirect the user to the KYC
@@ -5105,7 +5105,7 @@ regulatory compliance.
:query code=CODE:
OAuth 2.0 code argument.
:query state=STATE:
- OAuth 2.0 state argument with the H_PAYTO.
+ OAuth 2.0 state argument with the H_NORMALIZED_PAYTO.
.. note::
@@ -5358,7 +5358,8 @@ and freeze or unfreeze accounts suspected of money laundering.
interpretation. Defaults to ``INT64_MAX``, namely the biggest row id
possible in the database.
:query h_payto:
- *Optional*. Account selector. All matching accounts are returned if this
+ *Optional*. Account selector using the *normalized* payto URI.
+ All matching accounts are returned if this
filter is absent, otherwise only decisions for this account.
:query active:
*Optional*. If set to yes, only return active decisions, if no only
@@ -5399,7 +5400,7 @@ and freeze or unfreeze accounts suspected of money laundering.
// Which payto-address is this record about.
// Identifies a GNU Taler wallet or an affected bank account.
- h_payto: PaytoHash;
+ h_payto: NormalizedPaytoHash;
// Row ID of the record. Used to filter by offset.
rowid: Integer;
@@ -5545,7 +5546,7 @@ and freeze or unfreeze accounts suspected of money laundering.
}
-.. http:get:: /aml/$OFFICER_PUB/attributes/$H_PAYTO
+.. http:get:: /aml/$OFFICER_PUB/attributes/$H_NORMALIZED_PAYTO
Obtain attributes obtained as part of AML/KYC processes for a
given account.
@@ -5631,7 +5632,7 @@ and freeze or unfreeze accounts suspected of money laundering.
:http:statuscode:`403 Forbidden`:
The signature is invalid (or the AML officer not known).
:http:statuscode:`404 Not found`:
- The payto-address the decision was made for is unknown to the exchange.
+ The normalized payto-address the decision was made for is unknown to the exchange.
:http:statuscode:`409 Conflict`:
The designated AML account is not enabled or a more recent
decision was already submitted.
@@ -5645,13 +5646,14 @@ and freeze or unfreeze accounts suspected of money laundering.
// Human-readable justification for the decision.
justification: string;
- // Hash of payto-address of the account the decision is about.
+ // Hash of normalized payto-address of the account the decision is about.
// Identifies a GNU Taler wallet or an affected bank account.
- h_payto: PaytoHash;
+ h_payto: NormalizedPaytoHash;
- // Payto address of the account the decision is about.
+ // Full payto address of the account the decision is about.
// Optional. Must be given if the account is not yet
- // known to the exchange. If given, must match ``h_payto``.
+ // known to the exchange. If given, must match ``h_payto``
+ // (when normalized and then hashed).
// New since protocol **v21**.
payto_uri?: string;
@@ -5974,7 +5976,7 @@ designated account.
// the request (with a status code of 400).
request_timestamp: Timestamp;
- // payto://-URI of the account the reserve balance is to be
+ // Full payto://-URI of the account the reserve balance is to be
// wired to. Must be of the form: 'payto://$METHOD' for a
// wire method supported by this exchange (if the
// method is not supported, this is a bad request (400)).
@@ -6039,11 +6041,12 @@ designated account.
// what the exchange signs over.
close_time: Timestamp;
- // Hash of the wire account into which the remaining
- // balance will be transferred. Note: may be the
- // hash over ``payto://void/`, in which case the
- // balance is forfeit to the profit of the exchange.
- h_wire: HashCode;
+ // Hash of the full payto URI of the wire account
+ // into which the remaining balance will be transferred.
+ // Note: may be the hash over ``payto://void/`,
+ // in which case the balance is forfeit
+ // to the profit of the exchange.
+ h_wire: FullPaytoHash;
// This is a signature over a
// struct ``TALER_AccountDeleteConfirmationPS`` with purpose
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -1493,7 +1493,7 @@ KYC status checks
interface MerchantAccountKycRedirect {
- // Our bank wire account this is about.
+ // Full payto URI of the bank wire account this is about.
payto_uri: string;
// Hash of the salted payto://-URI of our
@@ -1548,7 +1548,8 @@ KYC status checks
// request that would cause it to exceed hard limits).
limits?: AccountLimit[];
- // Array of wire transfer instructions (including
+ // Array of full payto://-URIs with
+ // wire transfer instructions (including
// optional amount and subject) for a KYC auth wire
// transfer. Set only if this is required
// to get the given exchange working.
@@ -1596,7 +1597,7 @@ into any of the active bank accounts of an instance.
interface AccountAddDetails {
- // payto:// URI of the account.
+ // Full payto:// URI of the account.
payto_uri: string;
// URL from where the merchant can download information
@@ -1711,7 +1712,7 @@ into any of the active bank accounts of an instance.
interface BankAccountEntry {
- // payto:// URI of the account.
+ // Full payto:// URI of the account.
payto_uri: string;
// Hash over the wire details (including over the salt).
@@ -1741,7 +1742,7 @@ into any of the active bank accounts of an instance.
interface BankAccountDetail {
- // payto:// URI of the account.
+ // Full payto:// URI of the account.
payto_uri: string;
// Hash over the wire details (including over the salt).
@@ -3215,7 +3216,7 @@ Informing the backend about incoming wire transfers
// Raw wire transfer identifier identifying the wire transfer (a base32-encoded value).
wtid: WireTransferIdentifierRawP;
- // Target account that received the wire transfer.
+ // Full payto://-URI of the bank account that received the wire transfer.
payto_uri: string;
// Base URL of the exchange that made the wire transfer.
@@ -3239,7 +3240,7 @@ Querying known wire transfers
**Request:**
- :query payto_uri: *Optional*. Filter for transfers to the given bank account (subject and amount MUST NOT be given in the payto URI).
+ :query payto_uri: *Optional*. Full payto://-URI to filter for transfers to the given bank account (subject and amount MUST NOT be given in the payto:// URI). Note that the URI must be URL-encoded.
:query before: *Optional*. Filter for transfers executed before the given timestamp.
@@ -3275,7 +3276,7 @@ Querying known wire transfers
// Raw wire transfer identifier identifying the wire transfer (a base32-encoded value).
wtid: WireTransferIdentifierRawP;
- // Target account that received the wire transfer.
+ // Full payto://-URI of the bank account that received the wire transfer.
payto_uri: string;
// Base URL of the exchange that made the wire transfer.
