taler-docs

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

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

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