taler-docs

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

post-orders-ORDER_ID-claim.rst (2037B)

      1 .. http:post:: [/instances/$INSTANCE]/orders/$ORDER_ID/claim
      2 
      3   Wallet claims ownership (via nonce) over an order.  By claiming
      4   an order, the wallet obtains the full contract terms, and thereby
      5   implicitly also the hash of the contract terms it needs for the
      6   other ``public`` APIs to authenticate itself as the wallet that
      7   is indeed eligible to inspect this particular order's status.
      8 
      9   **Request:**
     10 
     11   The request must be a `ClaimRequest`.
     12 
     13   **Response:**
     14 
     15   :http:statuscode:`200 OK`:
     16     The client has successfully claimed the order.
     17     The response contains the :ref:`contract terms <contract-terms>`.
     18   :http:statuscode:`404 Not found`:
     19     The backend is unaware of the instance or order.
     20     Returned with ``TALER_EC_MERCHANT_POST_ORDERS_ID_CLAIM_NOT_FOUND``.
     21   :http:statuscode:`409 Conflict`:
     22     Someone else has already claimed the same order ID with a different nonce.
     23     Returned with ``TALER_EC_MERCHANT_POST_ORDERS_ID_CLAIM_ALREADY_CLAIMED``.
     24   :http:statuscode:`413 Request entity too large`:
     25     The uploaded body is to long, it exceeds the size limit.
     26     Returned with an error code of
     27     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     28   :http:statuscode:`500 Internal Server Error`:
     29     The server experienced an internal failure.
     30     Returned with ``TALER_EC_GENERIC_DB_COMMIT_FAILED``,
     31     ``TALER_EC_GENERIC_DB_SOFT_FAILURE`` or
     32     ``TALER_EC_GENERIC_FAILED_COMPUTE_JSON_HASH``.
     33 
     34   **Details:**
     35 
     36   .. ts:def:: ClaimRequest
     37 
     38     interface ClaimRequest {
     39       // Nonce to identify the wallet that claimed the order.
     40       nonce: EddsaPublicKey;
     41 
     42       // Token that authorizes the wallet to claim the order.
     43       // *Optional* as the merchant may not have required it
     44       // (``create_token`` set to ``false`` in `PostOrderRequest`).
     45       token?: ClaimToken;
     46     }
     47 
     48   .. ts:def:: ClaimResponse
     49 
     50     interface ClaimResponse {
     51       // Contract terms of the claimed order
     52       contract_terms: ContractTerms;
     53 
     54       // Signature by the merchant over the contract terms.
     55       sig: EddsaSignature;
     56     }