taler-docs

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

post-orders-ORDER_ID-unclaim.rst (1881B)

      1 .. http:post:: [/instances/$INSTANCE]/orders/$ORDER_ID/unclaim
      2 
      3   Wallet releases ownership over an order. By unclaiming an
      4   order, it becomes possible for another wallet to claim it.
      5   This is useful if a user abandons buying the order with one
      6   wallet but then wants to pay with a different wallet.
      7 
      8   @since protocol **v26**.
      9 
     10   **Request:**
     11 
     12   The request must be an `UnclaimRequest`.
     13 
     14   **Response:**
     15 
     16   :http:statuscode:`204 No content`:
     17     The client has successfully unclaimed the order.
     18   :http:statuscode:`400 Bad request`:
     19     The request is malformed. Returned with
     20     ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     21   :http:statuscode:`403 Forbidden`:
     22     The provided unclaim signature is invalid.
     23     Returned with ``TALER_EC_MERCHANT_POST_ORDERS_UNCLAIM_SIGNATURE_INVALID``.
     24   :http:statuscode:`404 Not found`:
     25     The backend is unaware of the instance or claimed order.
     26 
     27     Applicable error codes:
     28     * ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``
     29     * ``TALER_EC_MERCHANT_POST_ORDERS_ID_CLAIM_NOT_FOUND``
     30 
     31     The latter includes cases where the order was already
     32     paid as well as cases where the order does not exist or
     33     was simply not claimed.
     34 
     35   :http:statuscode:`500 Internal Server Error`:
     36     The server experienced an internal failure.
     37     Returned with ``TALER_EC_GENERIC_DB_COMMIT_FAILED`` or
     38     ``TALER_EC_GENERIC_DB_SOFT_FAILURE``.
     39 
     40 
     41   **Details:**
     42 
     43   .. ts:def:: UnclaimRequest
     44 
     45     interface UnclaimRequest {
     46       // Signature using the key of the claim nonce
     47       // to affirm unclaiming of the order.
     48       unclaim_sig: EddsaSignature;
     49 
     50       // Nonce to identify the wallet that claimed the order,
     51       // public key matching ``unclaim_sig``.
     52       nonce: EddsaPublicKey;
     53 
     54       // Hash of the order's contract terms, used
     55       // to enable signature verification without
     56       // database access.
     57       h_contract: HashCode;
     58     }