taler-docs

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

post-challenge-CHALLENGE_ID.rst (2320B)

      1 .. http:post:: [/instances/$INSTANCE]/challenge/$CHALLENGE_ID
      2 
      3   Send TAN code for the ``CHALLENGE_ID`` challenge.
      4 
      5   This request can be posted several times to trigger TAN retransmission when
      6   the current code has expired or too many confirmation attempts have been
      7   made.
      8 
      9   This endpoint is not authenticated, it may be used even when mandatory TAN
     10   channels were not validated yet.
     11 
     12   @since **v21**
     13 
     14   **Request:**
     15 
     16   The request body must be a JSON object, but can otherwise be empty
     17   (so just send '{}').
     18 
     19   **Response:**
     20 
     21   :http:statuscode:`200 Ok`:
     22     The TAN code has been sent. The body will be a `ChallengeRequestResponse`.
     23   :http:statuscode:`404 Not Found`:
     24     The challenge was not found.
     25     Returned with ``TALER_EC_MERCHANT_TAN_CHALLENGE_UNKNOWN``.
     26   :http:statuscode:`410 Gone`:
     27     The challenge was already solved.
     28     Returned with ``TALER_EC_MERCHANT_TAN_CHALLENGE_SOLVED``.
     29   :http:statuscode:`413 Request entity too large`:
     30     The uploaded body is to long, it exceeds the size limit.
     31     Returned with an error code of
     32     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     33   :http:statuscode:`429 Too many requests`:
     34     Too many challenges are active right now,
     35     you must wait or confirm current challenges.
     36     Returned with ``TALER_EC_MERCHANT_TAN_TOO_EARLY``.
     37   :http:statuscode:`500 Internal Server Error`:
     38     The server experienced an internal failure.
     39     Returned with ``TALER_EC_GENERIC_DB_COMMIT_FAILED``,
     40     ``TALER_EC_GENERIC_DB_SOFT_FAILURE``,
     41     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``,
     42     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE`` or
     43     ``TALER_EC_GENERIC_ALLOCATION_FAILURE``.
     44   :http:statuscode:`501 Not Implemented`:
     45     The challenge channel (e.g. TOTP) is not yet supported.
     46     Returned with ``TALER_EC_GENERIC_FEATURE_NOT_IMPLEMENTED``.
     47   :http:statuscode:`502 Bad Gateway`:
     48     TAN transmition via ``tan_channel`` failed.
     49     Returned with ``TALER_EC_MERCHANT_TAN_MFA_HELPER_EXEC_FAILED``.
     50 
     51   **Details:**
     52 
     53   .. ts:def:: ChallengeRequestResponse
     54 
     55     interface ChallengeRequestResponse {
     56       // How long does the client have to solve the
     57       // challenge.
     58       solve_expiration: Timestamp;
     59 
     60       // What is the earlist time at which the client
     61       // may request a new challenge to be transmitted?
     62       earliest_retransmission: Timestamp;
     63     }