taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-challenge-CHALLENGE_ID-confirm.rst (2307B)

      1 .. http:post:: [/instances/$INSTANCE]/challenge/$CHALLENGE_ID/confirm
      2 
      3   Solves the ``CHALLENGE_ID`` challenge and allows performing the protected operation.
      4 
      5   @since **v21**
      6 
      7   When the challenge is confirmed, you can call the protected endpoint again
      8   with ``CHALLENGE_ID`` in the ``Taler-Challenge-Ids`` HTTP header and the
      9   original request body.
     10 
     11   This endpoints is not authenticated for token creation challenges. Too many
     12   unsuccessful attempts to confirm token creation challenges block the
     13   account.
     14 
     15   This endpoint may be used even when mandatory TAN channels
     16   were not validated yet.
     17 
     18   **Request:**
     19 
     20   The request body must be a `MerchantChallengeSolveRequest`.
     21 
     22   **Response:**
     23 
     24   :http:statuscode:`204 No Content`:
     25     The challenge was solved.
     26   :http:statuscode:`404 Not Found`:
     27     The challenge was not found.
     28     Returned with ``TALER_EC_MERCHANT_TAN_CHALLENGE_UNKNOWN``.
     29   :http:statuscode:`409 Conflict`:
     30     Wrong TAN, returned with an
     31     error code of ``TALER_EC_MERCHANT_TAN_CHALLENGE_FAILED``
     32     in a response of type `MerchantChallengeFailedResponse`.
     33   :http:statuscode:`429 Too many requests`:
     34     Too many failed confirmation attempts, a new TAN must be requested.
     35     Returned with ``TALER_EC_MERCHANT_TAN_TOO_MANY_ATTEMPTS``.
     36   :http:statuscode:`500 Internal Server Error`:
     37     The server experienced an internal failure.
     38     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
     39 
     40   **Details:**
     41 
     42   .. ts:def:: MerchantChallengeSolveRequest
     43 
     44     interface MerchantChallengeSolveRequest {
     45 
     46       // The TAN code that solves $CHALLENGE_ID.
     47       tan: string;
     48     }
     49 
     50   .. ts:def:: MerchantChallengeFailedResponse
     51 
     52     interface MerchantChallengeFailedResponse {
     53 
     54       // Numeric `error code <error-codes>` unique to the condition.
     55       // The other arguments are specific to the error value reported here.
     56       code: ErrorCode;
     57 
     58       // Human-readable description of the error, i.e. "missing parameter", "commitment violation", ...
     59       // Should give a human-readable hint about the error's nature. Optional, may change without notice!
     60       hint?: string;
     61 
     62       // Optional detail about the specific input value that failed. May change without notice!
     63       detail?: string;
     64 
     65       // Counter with the number of attempts left.
     66       retry_counter: Integer;
     67     }