commit 964a27acc72cec21306169c757d1abd668a926af
parent f74c27c38d3d91e2c11624b80141efac15fd542e
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Wed, 18 Jun 2025 23:26:02 +0200
update documentation with current status on #9556
Diffstat:
| M | core/api-merchant.rst | | | 129 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------- |
1 file changed, 119 insertions(+), 10 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -40,7 +40,7 @@ must be created after the installation. In case *no* default instance is
found - or its credentials got lost -, the administrator can use the default
instance's rights by resorting on the ``--auth`` command line option, or by
restarting the service by providing an environment variable called
-``TALER_MERCHANT_TOKEN``.
+``TALER_MERCHANT_PASSWORD``.
Each instance (default and others) has a base URL. The resources under
this base URL are divided into to categories:
@@ -125,15 +125,15 @@ Currently, the ``/private/auth/`` API supports two main authentication methods i
Scopes
^^^^^^
-Access tokens can be requested with a (limiting) scope. Available scopes are:
+Access tokens can be requested with a (limiting) scope. Available scopes and their associated permissions are:
-* ``readonly``: Access to APIs using ``GET`` requests is always allowed.
-* ``write`` (*deprecated*): See ``all``.
-* ``all`` (**v42**): General access to all APIs and endpoints.
-* ``order-simple`` (**v42**): Allows the creation of orders and checking of payment status.
-* ``order-pos`` (**v42**): Same as ``order-simple`` and allows inventory locking.
-* ``order-mgmt`` (**v42**): Same as ``order-simple`` and also allows refunding.
-* ``order-full`` (**v42**): Same ``order-pos`` and ``order-mgmt`` combined.
+* ``readonly``: ``*-read`` -- Access to APIs using ``GET`` requests is always allowed.
+* ``write`` (*deprecated*): See ``admin``.
+* ``admin``: ``*`` -- General access to all APIs and endpoints. (Since **v42**)
+* ``order-simple``: ``orders-read``, ``orders-write`` -- Allows the creation of orders and checking of payment status. (Since **v42**)
+* ``order-pos``: ``orders-read``, ``orders-write``, ``inventory-lock`` -- Same as ``order-simple`` and allows inventory locking. (Since **v42**)
+* ``order-mgmt``: ``orders-read``, ``orders-write``, ``orders-refund`` -- Same as ``order-simple`` and also allows refunding. (Since **v42**)
+* ``order-full``: ``orders-read``, ``orders-write``, ``inventory-lock``, ``orders-refund`` -- Same ``order-pos`` and ``order-mgmt`` combined. (Since **v42**)
Since **v42** the scope may be suffixed with ``:refreshable``, e.g. ``order-pos:refreshable``.
This allows the token to be refreshed at the token endpoint.
@@ -1081,6 +1081,8 @@ Setting up instances
This request will be used to create a new merchant instance in the backend.
It is only available for the implicit ``default`` instance.
+ **Required permission:** ``instances-write``
+
**Request:**
The request must be a `InstanceConfigurationMessage`.
@@ -1159,6 +1161,8 @@ Setting up instances
that matches either the credential required by the instance being modified
OR the ``default`` instance, depending on the access path used.
+ **Required permission:** ``instances-auth-write``
+
**Request** the request must be an `InstanceAuthConfigurationMessage`.
:http:statuscode:`204 No content`:
@@ -1200,7 +1204,9 @@ Setting up instances
.. http:post:: [/instances/$INSTANCE]/private/token
- **Request:**
+ **Required permission:** ``instances-token-write``
+
+ **Request:**
The request must be a `LoginTokenRequest`.
@@ -1266,6 +1272,8 @@ Setting up instances
that matches either the credential required by the instance being modified
OR the ``default`` instance, depending on the access path used.
+ **Required permission:** ``instances-token-write``
+
**Request**
The request must be a `InstanceReconfigurationMessage`.
@@ -1336,6 +1344,7 @@ Inspecting instances
This is used to return the list of all the merchant instances.
It is only available for the implicit ``default`` instance.
+ **Required permission:** ``instances-read``
**Response:**
@@ -1395,6 +1404,8 @@ Inspecting instances
that matches either the credential required by the instance being modified
OR the ``default`` instance, depending on the access path used.
+ **Required permission:** ``instances-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -1467,6 +1478,8 @@ Getting statistics
SLUG will be returned.
Since protocol **vSTATISTICS**.
+ **Required permission:** ``statistics-read``
+
**Request:**
:query by: *Optional*. If set to "BUCKET", only statistics by bucket will be returned. If set to "INTERVAL", only statistics kept by interval will be returned. If not set or set to "ANY", both will be returned.
@@ -1543,6 +1556,8 @@ Getting statistics
SLUG will be returned.
Since protocol **vSTATISTICS**.
+ **Required permission:** ``statistics-read``
+
**Request:**
:query by: *Optional*. If set to "BUCKET", only statistics by bucket will be returned. If set to "INTERVAL", only statistics kept by interval will be returned. If not set or set to "ANY", both will be returned.
@@ -1628,6 +1643,8 @@ Deleting instances
the instance that is being deleted or the ``default``
instance, depending on the access path used.
+ **Required permission:** ``instances-write``
+
**Request:**
:query purge: *Optional*. If set to YES, the instance will be fully
@@ -1662,6 +1679,8 @@ KYC status checks
as to the KYC status of the respective account
and returns the result.
+ **Required permission:** ``instances-kyc-read``
+
**Request:**
:query h_wire=H_WIRE: *Optional*. If specified, the KYC check should return the KYC status only for this wire account. Otherwise, for all wire accounts.
@@ -1818,6 +1837,8 @@ into any of the active bank accounts of an instance.
This is used to add an account to an instance.
+ **Required permission:** ``accounts-write``
+
**Request:**
The request must have an `AccountAddDetails` body.
@@ -1897,6 +1918,8 @@ into any of the active bank accounts of an instance.
This is used to update a bank account.
+ **Required permission:** ``accounts-write``
+
**Request:**
The request must be a `AccountPatchDetails`.
@@ -1934,6 +1957,8 @@ into any of the active bank accounts of an instance.
This is used to return the list of all the bank accounts
of an instance.
+ **Required permission:** ``accounts-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -1971,6 +1996,8 @@ into any of the active bank accounts of an instance.
This is used to obtain detailed information about a specific bank account.
+ **Required permission:** ``accounts-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -2007,6 +2034,8 @@ into any of the active bank accounts of an instance.
.. http:delete:: [/instances/$INSTANCE]/private/accounts/$H_WIRE
+ **Required permission:** ``accounts-write``
+
**Response:**
:http:statuscode:`204 No content`:
@@ -2037,6 +2066,8 @@ Managing product categories
and the number of products in each category.
Since API version **v16**.
+ **Required permission:** ``categories-read``
+
**Response:**
:http:statuscode:`200 Ok`:
@@ -2079,6 +2110,8 @@ Managing product categories
category.
Since API version **v16**.
+ **Required permission:** ``categories-read``
+
**Response:**
:http:statuscode:`200 Ok`:
@@ -2117,6 +2150,8 @@ Managing product categories
This is used to create a new category for the inventory.
Since API version **v16**.
+ **Required permission:** ``categories-write``
+
**Request:**
The request is a `CategoryCreateRequest`.
@@ -2155,6 +2190,8 @@ Managing product categories
This is used to edit a category.
Since API version **v16**.
+ **Required permission:** ``categories-write``
+
**Request:**
The request is a `CategoryCreateRequest`.
@@ -2169,6 +2206,8 @@ Managing product categories
This is used to delete a category.
Since API version **v16**.
+ **Required permission:** ``categories-write``
+
**Response:**
:http:statuscode:`204 No Content`:
@@ -2185,6 +2224,8 @@ Adding products to the inventory
This is used to add a product to the inventory.
+ **Required permission:** ``products-write``
+
**Request:**
The request must be a `ProductAddDetail`.
@@ -2264,6 +2305,8 @@ Adding products to the inventory
timestamp to indicate no intention/possibility of restocking, while a time
of zero is used to indicate "unknown".
+ **Required permission:** ``products-write``
+
**Request:**
The request must be a `ProductPatchDetail`.
@@ -2336,6 +2379,8 @@ Inspecting inventory
This is used to return the list of all items in the inventory.
+ **Required permission:** ``products-read``
+
**Request:**
:query limit: *Optional*. At most return the given number of results. Negative for descending by row ID, positive for ascending by row ID. Default is ``20``. Since protocol **v12**.
@@ -2377,6 +2422,8 @@ Inspecting inventory
This is used to obtain detailed information about a product in the inventory.
+ **Required permission:** ``products-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -2448,6 +2495,8 @@ Inspecting inventory
Endpoint was introduced in protocol **v15**.
+ **Required permission:** ``products-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -2553,6 +2602,8 @@ Reserving inventory
If an order is for fewer items than originally locked, the difference
is automatically unlocked.
+ **Required permission:** ``products-lock``
+
**Request:**
The request must be a `LockRequest`.
@@ -2598,6 +2649,8 @@ Removing products from inventory
Delete information about a product. Fails if the product is locked by
anyone.
+ **Required permission:** ``products-write``
+
**Response:**
:http:statuscode:`204 No content`:
@@ -2638,6 +2691,8 @@ Creating orders
API is structured this way since the payment redirect URL is not unique
for every order, there might be varying parameters such as the session id.
+ **Required permission:** ``orders-write``
+
**Request:**
The request must be a `PostOrderRequest`.
@@ -3007,6 +3062,8 @@ Inspecting orders
Returns known orders up to some point in the past.
+ **Required permission:** ``orders-read``
+
**Request:**
:query paid: *Optional*. If set to yes, only return paid orders, if no only unpaid orders. Do not give (or use "all") to see all orders regardless of payment status.
@@ -3075,6 +3132,8 @@ Inspecting orders
the contract hash to authenticate, while for this API we assume that the
merchant is authenticated (as the endpoint is not ``public``).
+ **Required permission:** ``orders-read``
+
**Request:**
:query session_id: *Optional*. Session ID that the payment must be bound to. If not specified, the payment is not session-bound.
@@ -3291,6 +3350,8 @@ the contract!) to minimize risks from information leakage.
Forget fields in an order's contract terms that the merchant no
longer needs.
+ **Required permission:** ``orders-write``
+
**Request:**
The request must be a `forget request <ForgetRequest>`. The fields specified
@@ -3365,6 +3426,8 @@ Giving Refunds
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.
+ **Required permission:** ``orders-refund``
+
**Request:**
The request body is a `RefundRequest` object.
@@ -3440,6 +3503,8 @@ Informing the backend about incoming wire transfers
transfer information from the merchant's database (assuming we got a non-error
response from the exchange before).
+ **Required permission:** ``transfers-write``
+
**Request:**
The request must provide `transfer information <TransferInformation>`.
@@ -3486,6 +3551,8 @@ Querying known wire transfers
filter by. Thus, IF timestamp filters are given, transfers for which we have no
response from the exchange yet are automatically excluded.
+ **Required permission:** ``transfers-read``
+
**Request:**
: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.
@@ -3564,6 +3631,8 @@ once we got a reply from the exchange.
Here, the TID is the 'transfer_serial_id' of the transfer
to delete.
+ **Required permission:** ``transfers-write``
+
**Response:**
:http:statuscode:`204 No content`:
@@ -3586,6 +3655,8 @@ to validate that a customer made a payment.
This is used to associate an OTP device with an instance.
+ **Required permission:** ``otp-devices-write``
+
**Request:**
The request must be a `OtpDeviceAddDetails`.
@@ -3632,6 +3703,8 @@ to validate that a customer made a payment.
This is used to update an OTP device. It is useful when we need to change information in the OTP device or when we have mistake some information.
+ **Required permission:** ``otp-devices-write``
+
**Request:**
The request must be a `OtpDevicePatchDetails`.
@@ -3674,6 +3747,8 @@ to validate that a customer made a payment.
This is used to return the list of all the OTP devices.
+ **Required permission:** ``otp-devices-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -3713,6 +3788,8 @@ to validate that a customer made a payment.
provides inadequate query parameters, the ``otp_code`` is simply omitted
from the response.
+ **Required permission:** ``otp-devices-read``
+
**Query:**
:query faketime=TIMESTAMP: *Optional*. Timestamp in seconds to use when calculating the current OTP code of the device. Since protocol **v10**.
@@ -3783,6 +3860,8 @@ to validate that a customer made a payment.
.. http:delete:: [/instances/$INSTANCE]/private/otp-devices/$DEVICE_ID
+ **Required permission:** ``otp-devices-write``
+
**Response:**
:http:statuscode:`204 No content`:
@@ -3847,6 +3926,8 @@ Adding templates
This is used to create a template.
+ **Required permission:** ``templates-write``
+
**Request:**
The request must be a `TemplateAddDetails`.
@@ -3925,6 +4006,8 @@ Editing templates
This is used to update a template. It is useful when we need to change information in the template or when we have mistake some information.
+ **Required permission:** ``templates-write``
+
**Request:**
The request must be a `TemplatePatchDetails`.
@@ -3973,6 +4056,8 @@ Inspecting template
This is used to return the list of all the templates.
+ **Required permission:** ``templates-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -4009,6 +4094,8 @@ Inspecting template
This is used to obtain detailed information about a specific template.
+ **Required permission:** ``templates-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -4061,6 +4148,8 @@ Removing template
This is used to delete information about a template. If we no longer use it.
+ **Required permission:** ``templates-write``
+
**Response:**
:http:statuscode:`204 No content`:
@@ -4161,6 +4250,8 @@ Adding webhooks
This is used to create a webhook.
+ **Required permission:** ``webhooks-write``
+
**Request:**
The request must be a `WebhookAddDetails`.
@@ -4207,6 +4298,8 @@ Editing webhooks
This is used to update a webhook.
+ **Required permission:** ``webhooks-write``
+
**Request:**
The request must be a `WebhookPatchDetails`.
@@ -4252,6 +4345,8 @@ Inspecting webhook
This is used to return all the webhooks that are present in our backend.
+ **Required permission:** ``webhooks-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -4290,6 +4385,8 @@ Inspecting webhook
This is used to obtain detailed information about apecific template.
+ **Required permission:** ``webhooks-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -4329,6 +4426,8 @@ Removing webhook
This is used to delete information about a webhook.
+ **Required permission:** ``webhooks-write``
+
**Response:**
:http:statuscode:`204 No content`:
@@ -4357,6 +4456,8 @@ Creating token families
This is used to create a token family.
+ **Required permission:** ``tokenfamilies-write``
+
**Request:**
The request must be a `TokenFamilyCreateRequest`.
@@ -4436,6 +4537,8 @@ Updating token families
This is used to update a token family.
+ **Required permission:** ``tokenfamilies-write``
+
**Request:**
The request must be a `TokenFamilyUpdateRequest`.
@@ -4484,6 +4587,8 @@ Inspecting token families
This is used to list all configured token families for an instance.
+ **Required permission:** ``tokenfamilies-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -4531,6 +4636,8 @@ Inspecting token families
This is used to get detailed information about a specific token family.
+ **Required permission:** ``tokenfamilies-read``
+
**Response:**
:http:statuscode:`200 OK`:
@@ -4609,6 +4716,8 @@ Deleting token families
This is used to delete a token family. Issued tokens of this family will not
be spendable anymore.
+ **Required permission:** ``tokenfamilies-write``
+
**Response:**
:http:statuscode:`204 No content`:
