commit f9a453f19dbabba5174007fb071131cbd1a1668f
parent 8b3997a26458da1deaf26759f81836f7bbedb05f
Author: bohdan-potuzhnyi <bohdan.potuzhnyi@gmail.com>
Date: Tue, 1 Sep 2026 17:55:08 +0200
[mixed-payments] small update
Diffstat:
7 files changed, 29 insertions(+), 21 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -29,7 +29,7 @@ Merchant Backend RESTful API
Version History
---------------
-The currently implemented protocol version is **v35**.
+The currently implemented protocol version is **v42**.
* The Android PoS app is currently targeting **v20**.
* The SPA is currently targeting **vXX**.
@@ -69,6 +69,19 @@ The currently implemented protocol version is **v35**.
* ``v35``: adds ``exchange_payto_uri`` to
:http:get:`[/instances/$INSTANCE]/private/transfers`,
passing on the exchange account reported by exchange protocol **v39**
+* ``v36``: allows token families with indefinite validity
+* ``v37``: adds expiration filtering to the private order history
+* ``v38``: adds reporting and repair of an order's wired status
+* ``v39``: returns a login token after a successful password reset
+* ``v40``: requires the current password when changing merchant credentials
+* ``v41``: returns merchant details and compatible exchange candidates for
+ wallet templates
+* ``v42``: adds the additive ``amount_external`` field for orders settled
+ partly outside of Taler, the ``/private/orders/$ORDER_ID/collect`` endpoint
+ for completing zero-Taler orders without a wallet, the
+ ``/private/orders/$ORDER_ID/refund-external`` endpoint for recording
+ externally settled refunds, and exposes both through order status
+ (see :doc:`DD 96 </design-documents/096-partial-payments>`)
**Upcoming versions:**
@@ -79,12 +92,6 @@ The currently implemented protocol version is **v35**.
* ``vTokenFountains``: adds fountains for distributing promotional
merchant tokens
(see :doc:`DD 98 </design-documents/098-token-fountains>`)
-* ``vMixedPayments``: adds the additive ``amount_external`` field for orders
- settled partly outside of Taler, the ``/private/orders/$ORDER_ID/collect``
- endpoint for completing zero-Taler orders without a wallet, the
- ``/private/orders/$ORDER_ID/refund-external`` endpoint for recording
- externally settled refunds, and exposes both through order status
- (see :doc:`DD 96 </design-documents/096-partial-payments>`)
**Ideas for future version:**
@@ -1852,7 +1859,7 @@ Orders
// amount and all entries here. If present, all entries and (for
// v1 orders) all choices must use the currency of the Taler
// ``amount``. Never contains a ``taler`` entry.
- // @since protocol **vMixedPayments**.
+ // @since protocol **v42**.
amount_external?: ExternalPaymentInfo[];
}
@@ -2145,7 +2152,7 @@ and is thus not yet buyer-specific.
// selected choice's ``amount`` for v1 contracts) remains the amount
// paid with Taler; the full order total is the sum of that amount
// and all entries here. See `ExternalPaymentInfo`.
- // @since protocol **vMixedPayments**.
+ // @since protocol **v42**.
amount_external?: ExternalPaymentInfo[];
}
diff --git a/core/merchant/delete-private-orders-ORDER_ID.rst b/core/merchant/delete-private-orders-ORDER_ID.rst
@@ -4,7 +4,7 @@
last 10 years (or whatever ``TAX_RECORD_EXPIRATION`` is set to) or was
claimed but is unpaid and thus still a valid offer.
- Since protocol **vMixedPayments**, an order that carries externally
+ Since protocol **v42**, an order that carries externally
settled payments (``amount_external``) can only be deleted by explicitly
passing ``force``, as such an order may have received payments outside of
Taler that the merchant should resolve manually first.
@@ -31,7 +31,7 @@
Returned with ``TALER_EC_MERCHANT_PRIVATE_DELETE_ORDERS_ALREADY_PAID``,
``TALER_EC_MERCHANT_PRIVATE_DELETE_ORDERS_AWAITING_PAYMENT`` or
``TALER_EC_MERCHANT_PRIVATE_DELETE_ORDERS_EXTERNALLY_PAID`` (the latter
- since protocol **vMixedPayments**, when the order carries externally
+ since protocol **v42**, when the order carries externally
settled payments and ``force`` was not set).
:http:statuscode:`500 Internal Server Error`:
The server experienced an internal failure.
diff --git a/core/merchant/get-private-orders-ORDER_ID.rst b/core/merchant/get-private-orders-ORDER_ID.rst
@@ -117,7 +117,7 @@
// [/instances/$INSTANCE]/private/orders/$ORDER_ID/refund-external.
// These are bookkeeping entries only; empty array if there are
// none.
- // @since protocol **vMixedPayments**.
+ // @since protocol **v42**.
refunds_external: ExternalRefundInfo[];
// Status URL, can be used as a redirect target for the browser
diff --git a/core/merchant/post-orders-ORDER_ID-pay.rst b/core/merchant/post-orders-ORDER_ID-pay.rst
@@ -107,7 +107,7 @@
this request, so the request does not describe the payment that was
made. The response is an `AlreadyPaidChoiceResponse` and contains the
``choice_index`` the order was actually paid with.
- Since protocol **vMixedPayments**.
+ Since protocol **v42**.
* ``MERCHANT_POST_ORDERS_ID_PAY_ALREADY_PAID``: The order was already
fully paid by another wallet. The response includes refund signatures
for the coins.
diff --git a/core/merchant/post-private-orders-ORDER_ID-collect.rst b/core/merchant/post-private-orders-ORDER_ID-collect.rst
@@ -27,7 +27,7 @@
**Required permission:** ``orders-write`` (see :ref:`Scopes <merchant-api-scopes>`)
- Since protocol **vMixedPayments**.
+ Since protocol **v42**.
**Request:**
diff --git a/core/merchant/post-private-orders-ORDER_ID-refund-external.rst b/core/merchant/post-private-orders-ORDER_ID-refund-external.rst
@@ -31,7 +31,7 @@
**Required permission:** ``orders-refund`` (see :ref:`Scopes <merchant-api-scopes>`)
- Since protocol **vMixedPayments**.
+ Since protocol **v42**.
**Request:**
diff --git a/core/merchant/post-private-orders-ORDER_ID-refund.rst b/core/merchant/post-private-orders-ORDER_ID-refund.rst
@@ -3,9 +3,9 @@
Increase the refund amount associated with a given order. The user should be
redirected to the ``taler_refund_uri`` to trigger refund processing in the wallet.
- Since ``vMixedPayments``. For orders with refunds settled through external payment methods,
- the cumulative Taler refund must not exceed the full order total minus those
- external refunds.
+ Since **v42**. For orders with refunds settled through external payment
+ methods, the cumulative Taler refund must not exceed the full order total
+ minus those external refunds.
**Required permission:** ``orders-refund`` (see :ref:`Scopes <merchant-api-scopes>`)
@@ -29,11 +29,12 @@
Returned with ``TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN``.
:http:statuscode:`409 Conflict`:
The refund amount exceeds the amount originally paid, the combined Taler
- and external refunds would exceed the full order total (since ``vMixedPayments``), or the order was
- not yet paid.
+ and external refunds would exceed the full order total (since **v42**), or
+ the order was not yet paid.
Returned with ``TALER_EC_MERCHANT_GENERIC_CURRENCY_MISMATCH`` or
``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_ORDER_UNPAID``,
- ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_INCONSISTENT_AMOUNT`` (since ``vMixedPayments``).
+ ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_INCONSISTENT_AMOUNT``
+ (since **v42**).
:http:statuscode:`410 Gone`:
It is too late for refunds, the exchange may have already wired the funds
to the merchant.
