commit 6e583f0e57e0fa8c9d6d4efbd781d2465e4dacb4
parent 133071fa57f0b7bd2e272505b99eca59c35b029a
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 29 Mar 2026 20:44:46 +0200
document API more precisely
Diffstat:
4 files changed, 58 insertions(+), 7 deletions(-)
diff --git a/core/merchant/get-orders-ORDER_ID.rst b/core/merchant/get-orders-ORDER_ID.rst
@@ -60,6 +60,10 @@
trigger repurchase detection.
Note that **if** the contract lacks a ``public_reorder_url``
the backend will instead return a ``403 Forbidden`` response.
+ :http:statuscode:`400 Bad Request`:
+ The request parameters are malformed.
+ Returned with an applicable Taler error code, such as
+ ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
:http:statuscode:`402 Payment required`:
The response is a `StatusUnpaidResponse`.
:http:statuscode:`403 Forbidden`:
diff --git a/core/merchant/get-private-reports-REPORT_ID.rst b/core/merchant/get-private-reports-REPORT_ID.rst
@@ -51,6 +51,9 @@
// Report frequency shift
report_frequency_shift: RelativeTime;
+ // Timestamp of the next scheduled transmission.
+ next_transmission: Timestamp;
+
// Numeric `error code <error-codes>` unique to the
// error encountered in generating the latest report.
// Absent if there was no error.
diff --git a/core/merchant/post-orders-ORDER_ID-abort.rst b/core/merchant/post-orders-ORDER_ID-abort.rst
@@ -15,10 +15,12 @@
**Response:**
:http:statuscode:`200 OK`:
- The merchant accepted the request, and passed it on to the exchange. The body is a
- a `abort response <AbortResponse>`. Note that the exchange
- MAY still have encountered errors in processing. Those will then be part of
- the body. Wallets MUST carefully consider errors for each of the coins as
+ The merchant accepted the request, and passed it on to the exchange(s).
+ The body is an
+ `abort response <AbortResponse>`.
+ Note that the exchange MAY still have encountered errors in processing.
+ Those will then be part of the body.
+ Wallets MUST carefully consider errors for each of the coins as
returned by the exchange.
:http:statuscode:`400 Bad request`:
Either the client request is malformed or some specific processing error
@@ -36,12 +38,17 @@
Aborting the payment is not allowed, as the original payment did succeed.
It is possible that a different wallet succeeded with the payment. This
wallet should thus try to refresh all of the coins involved in the payment.
- :http:statuscode:`502 Bad gateway`:
- The merchant's interaction with the exchange failed in some way.
- The error from the exchange is included.
:http:statuscode:`500 Internal Server Error`:
The server experienced an internal failure.
Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
+ :http:statuscode:`502 Bad gateway`:
+ The merchant's interaction with some exchange failed in some way.
+ The errors from the exchanges are included.
+ The body is a `abort response <AbortResponse>`.
+ Note that the exchange MAY still have encountered errors in processing.
+ Those will then be part of the body.
+ Wallets MUST carefully consider errors for each of the coins as
+ returned by the exchange.
:http:statuscode:`504 Gateway timeout`:
The merchant's interaction with the exchange took too long.
The client might want to try again later.
diff --git a/core/merchant/post-orders-ORDER_ID-pay.rst b/core/merchant/post-orders-ORDER_ID-pay.rst
@@ -28,6 +28,34 @@
* ``MERCHANT_POST_ORDERS_ID_PAY_DENOMINATION_KEY_NOT_FOUND``: Wallet tried
to pay with a non-existent denomination.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_DENOMINATION_DEPOSIT_EXPIRED``: The
+ denomination used for payment has expired for deposits.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_AGE_COMMITMENT_MISSING``: An age commitment
+ is required but was not provided.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_AGE_COMMITMENT_SIZE_MISMATCH``: The age
+ commitment has the wrong number of public keys.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_AGE_VERIFICATION_FAILED``: The age
+ verification signature is invalid.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_AGE_COMMITMENT_HASH_MISSING``: The age
+ commitment hash is required but was not provided.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_PAYMENT_INSUFFICIENT``: The total payment
+ amount is insufficient to cover the order.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_INSUFFICIENT_DUE_TO_FEES``: The payment
+ is insufficient because fees exceed what is covered.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_TOKEN_ISSUE_SIG_INVALID``: A token issue
+ signature is invalid.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_TOKEN_USE_SIG_INVALID``: A token use
+ signature is invalid.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_TOKEN_COUNT_MISMATCH``: The number of
+ input tokens does not match the expected count.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_TOKEN_ENVELOPE_COUNT_MISMATCH``: The number
+ of output token envelopes does not match the expected count.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_CHOICE_INDEX_OUT_OF_BOUNDS``: The
+ ``choice_index`` in the wallet data is out of range.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_CHOICE_INDEX_MISSING``: The
+ ``choice_index`` is required but was not provided.
+ * ``MERCHANT_GENERIC_EXCHANGE_UNTRUSTED``: The exchange used for a coin
+ is not trusted by this merchant.
:http:statuscode:`402 Payment required`:
There used to be a sufficient payment, but due to refunds the amount effectively
@@ -66,6 +94,15 @@
* ``MERCHANT_POST_ORDERS_ID_PAY_INSUFFICIENT_FUNDS``: Exchange reported insufficient
funds for one of the coins.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_ALREADY_PAID``: The order was already
+ fully paid by another wallet. The response includes refund signatures
+ for the coins.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_TOKEN_INVALID``: A token was already used
+ in a previous payment.
+ * ``MERCHANT_POST_ORDERS_ID_PAY_DONATION_AMOUNT_MISMATCH``: The donation
+ amount does not match the expected amount or exceeds the yearly limit.
+ * ``MERCHANT_GENERIC_CURRENCY_MISMATCH``: Coin currency does not match
+ the expected payment currency.
:http:statuscode:`410 Gone`:
The offer has expired and is no longer available or
