taler-docs

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

post-orders-ORDER_ID-paid.rst (2810B)

      1 .. http:post:: [/instances/$INSTANCE]/orders/$ORDER_ID/paid
      2 
      3   Prove that the client previously paid for an order by providing
      4   the merchant's signature from the `payment response <PaymentResponse>`.
      5   Typically used by the customer's wallet if it receives a request for
      6   payment for an order that it already paid. This is more compact than
      7   re-transmitting the full payment details.
      8   Note that this request does include the
      9   usual ``h_contract`` argument to authenticate the wallet and
     10   to allow the merchant to verify the signature before checking
     11   with its own database.
     12 
     13   **Request:**
     14 
     15   The request must be a `paid request <PaidRequest>`.
     16 
     17   **Response:**
     18 
     19   :http:statuscode:`200 Ok`:
     20     The merchant accepted the signature.
     21     The ``frontend`` should now fulfill the contract.
     22     Note that it is possible that refunds have been granted.  Response is of type `PaidRefundStatusResponse`.
     23   :http:statuscode:`400 Bad request`:
     24     Either the client request is malformed or some specific processing error
     25     happened that may be the fault of the client as detailed in the JSON body
     26     of the response.
     27     Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     28   :http:statuscode:`403 Forbidden`:
     29     The signature was not valid.
     30     Returned with ``TALER_EC_MERCHANT_POST_ORDERS_ID_PAID_COIN_SIGNATURE_INVALID``.
     31   :http:statuscode:`404 Not found`:
     32     The merchant backend could not find the order or the instance
     33     and thus cannot process the request.
     34     Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN`` or
     35     ``TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN``.
     36   :http:statuscode:`413 Request entity too large`:
     37     The uploaded body is to long, it exceeds the size limit.
     38     Returned with an error code of
     39     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     40   :http:statuscode:`500 Internal Server Error`:
     41     The server experienced an internal failure.
     42     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
     43 
     44   **Details**:
     45 
     46   .. ts:def:: PaidRefundStatusResponse
     47 
     48     interface PaidRefundStatusResponse {
     49 
     50       // Text to be shown to the point-of-sale staff as a proof of
     51       // payment (present only if re-usable OTP algorithm is used).
     52       pos_confirmation?: string;
     53 
     54       // True if the order has been subjected to
     55       // refunds. False if it was simply paid.
     56       refunded: boolean;
     57     }
     58 
     59   .. ts:def:: PaidRequest
     60 
     61     interface PaidRequest {
     62       // Signature on ``TALER_PaymentResponsePS`` with the public
     63       // key of the merchant instance.
     64       sig: EddsaSignature;
     65 
     66       // Hash of the order's contract terms (this is used to authenticate the
     67       // wallet/customer and to enable signature verification without
     68       // database access).
     69       h_contract: HashCode;
     70 
     71       // Session id for which the payment is proven.
     72       session_id: string;
     73     }