commit 8fe45769a44c3c0a752d11fead4e0f2733778d44
parent 2ed6b8febaaae03d4fb17ddf6e7359cca0a5e392
Author: Florian Dold <florian@dold.me>
Date: Mon, 4 Aug 2025 18:34:49 +0200
merchant: self provisioning / 2FA draft
Diffstat:
| M | core/api-merchant.rst | | | 125 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 125 insertions(+), 0 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -102,6 +102,9 @@ https://merchant-backend.example.com/private
Generic Responses
-----------------
+The following (error) responses are applicable to all endpoints
+unless specified otherwise.
+
.. http:any:: *
:http:statuscode:`403 Forbidden`:
@@ -214,6 +217,20 @@ such as the implemented version of the protocol and the currency used.
// Since protocol **v6**.
exchanges: ExchangeConfigInfo[];
+ // Set when the merchant supports
+ // self-provisioning instances.
+ have_self_provisioning?: boolean;
+
+ // Tan channels that are required
+ // to be confirmed for an instance to
+ // be useable.
+ mandatory_tan_channels?: TanChannel[];
+
+ }
+
+ enum TanChannel {
+ SMS = "sms",
+ EMAIL = "email"
}
.. ts:def:: ExchangeConfigInfo
@@ -235,6 +252,111 @@ such as the implemented version of the protocol and the currency used.
master_pub: EddsaPublicKey;
}
+---------------
+Two Factor Auth
+---------------
+
+.. http:post:: [/instances/$INSTANCE]/auth-channels/$CHANNEL/validate
+
+ Request the validation of a 2FA channel.
+
+ This endpoint may be used even when mandatory TAN channels
+ were not validated yet.
+
+ :http:statuscode:`204 No Content`:
+ The channel has been successfully validated.
+ :http:statuscode:`202 Accepted`:
+ 2FA is required for this operation. This returns the `Challenge` response.
+
+ .. ts:def:: Challenge
+
+ interface Challenge {
+ // Unique identifier of the challenge to solve to run this protected
+ // operation.
+ challenge_id: string;
+ }
+
+.. http:post:: [/instances/$INSTANCE]/challenge/$CHALLENGE_ID
+
+ Send TAN code for the ``CHALLENGE_ID`` challenge.
+
+ This request can be posted several times to trigger TAN retransmission when the current code has expired or too many confirmation attempts have been made.
+
+ This endpoints is not authenticated for token creation challenges.
+
+ This endpoint may be used even when mandatory TAN channels
+ were not validated yet.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The TAN code have been sent. This returns `TanTransmission` response.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
+ :http:statuscode:`404 Not Found`:
+ The challenge was not found.
+ :http:statuscode:`429 Too many requests`:
+ Too many challenges are active right now, you must wait or confirm current challenges.
+ :http:statuscode:`502 Bad Gateway`:
+ * ``TALER_EC_BANK_TAN_CHANNEL_SCRIPT_FAILED``: TAN transmition via ``tan_channel`` failed.
+
+ **Details:**
+
+ .. ts:def:: TanTransmission
+
+ interface TanTransmission {
+ // Channel of the last successful transmission of the TAN challenge.
+ tan_channel: TanChannel;
+
+ // Info of the last successful transmission of the TAN challenge.
+ tan_info: string;
+ }
+
+ .. ts:def:: Challenge
+
+ interface Challenge {
+ // Unique identifier of the challenge to solve to run this protected
+ // operation.
+ challenge_id: string;
+ }
+
+.. http:post:: [/instances/$INSTANCE]/challenge/$CHALLENGE_ID/confirm
+
+ Solves the ``CHALLENGE_ID`` challenge and allows performing the protected operation.
+
+ When the challenge is confirmed, you can call the protected endpoint again with ``CHALLENGE_ID`` in the ``X-Challenge-Id`` HTTP header and an empty request body.
+
+ This endpoints is not authenticated for token creation challenges. Too many unsuccessful attempts to confirm token creation challenges block the account.
+
+ This endpoint may be used even when mandatory TAN channels
+ were not validated yet.
+
+ **Request:**
+
+ .. ts:def:: ChallengeSolve
+
+ interface ChallengeSolve {
+ // The TAN code that solves $CHALLENGE_ID
+ tan: string;
+ }
+
+ **Response:**
+
+ :http:statuscode:`204 No Content`:
+ The challenge is confirmed.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
+ :http:statuscode:`404 Not Found`:
+ The challenge was not found.
+ :http:statuscode:`409 Conflict`:
+ * ``TALER_EC_BANK_TAN_CHALLENGE_FAILED`` : wrong TAN.
+ * ``TALER_EC_BANK_TAN_CHALLENGE_EXPIRED`` : expired TAN.
+ :http:statuscode:`429 Too many requests`:
+ Too many failed confirmation attempts, a new TAN must be requested.
----------
Wallet API
@@ -1528,6 +1650,9 @@ Inspecting instances
that matches either the credential required by the instance being modified
OR the ``default`` instance, depending on the access path used.
+ This endpoint may be used even when mandatory TAN channels
+ were not validated yet.
+
**Required permission:** ``instances-read``
**Response:**
