taler-docs

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

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

      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   :http:statuscode:`409 Conflict`:
     21     Someone else has already claimed the same order ID with a different nonce.
     22   :http:statuscode:`500 Internal Server Error`:
     23     The server experienced an internal failure.
     24     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
     25 
     26   **Details:**
     27 
     28   .. ts:def:: ClaimRequest
     29 
     30     interface ClaimRequest {
     31       // Nonce to identify the wallet that claimed the order.
     32       nonce: EddsaPublicKey;
     33 
     34       // Token that authorizes the wallet to claim the order.
     35       // *Optional* as the merchant may not have required it
     36       // (``create_token`` set to ``false`` in `PostOrderRequest`).
     37       token?: ClaimToken;
     38     }
     39 
     40   .. ts:def:: ClaimResponse
     41 
     42     interface ClaimResponse {
     43       // Contract terms of the claimed order
     44       contract_terms: ContractTerms;
     45 
     46       // Signature by the merchant over the contract terms.
     47       sig: EddsaSignature;
     48     }