taler-docs

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

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

      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:`404 Not found`:
     37 
     38   **Details**:
     39 
     40   .. ts:def:: PaidRefundStatusResponse
     41 
     42     interface PaidRefundStatusResponse {
     43 
     44       // Text to be shown to the point-of-sale staff as a proof of
     45       // payment (present only if re-usable OTP algorithm is used).
     46       pos_confirmation?: string;
     47 
     48       // True if the order has been subjected to
     49       // refunds. False if it was simply paid.
     50       refunded: boolean;
     51     }
     52 
     53   .. ts:def:: PaidRequest
     54 
     55     interface PaidRequest {
     56       // Signature on ``TALER_PaymentResponsePS`` with the public
     57       // key of the merchant instance.
     58       sig: EddsaSignature;
     59 
     60       // Hash of the order's contract terms (this is used to authenticate the
     61       // wallet/customer and to enable signature verification without
     62       // database access).
     63       h_contract: HashCode;
     64 
     65       // Session id for which the payment is proven.
     66       session_id: string;
     67     }