taler-docs

get-private-orders-ORDER_ID.rst (10922B)

---

 .. http:get:: [/instances/$INSTANCE]/private/orders/$ORDER_ID
 
   Merchant checks the payment status of an order.  If the order exists but is not paid
   and not claimed yet, the response provides a redirect URL.  When the user goes to this URL,
   they will be prompted for payment.  Differs from the ``public`` API both
   in terms of what information is returned and in that the wallet must provide
   the contract hash to authenticate, while for this API we assume that the
   merchant is authenticated (as the endpoint is not ``public``).
 
   **Required permission:** ``orders-read`` (see :ref:`Scopes <merchant-api-scopes>`)
 
   **Request:**
 
   :query session_id: *Optional*. Session ID that the payment must be bound to.  If not specified, the payment is not session-bound.
   :query transfer: Deprecated in protocol **V6**. *Optional*. If set to "YES", try to obtain the wire transfer status for this order from the exchange. Otherwise, the wire transfer status MAY be returned if it is available.
   :query timeout_ms: *Optional*. Timeout in milliseconds to wait for a payment if the answer would otherwise be negative (long polling).
   :query lp_not_etag=ETAG: *Optional*.
     Specifies what status change we are long-polling for.
     If specified, the endpoint will only return once the returned "Etag"
     would differ from the ETAG specified by the client. The "Etag"
     is computed over the entire response body, and thus assured to change
     whenever any data point in the response changes. This is ideal for
     clients that want to learn about any change in the response.  Clients
     using this query parameter should probably also set a "If-none-match"
     HTTP header so that if the ``timeout_ms`` expires, they can get back
     a "304 Not modified" with an empty body if nothing changed.
   :query allow_refunded_for_repurchase: *Optional*. Since protocol **v9** refunded orders are only returned under "already_paid_order_id" if this flag is set explicitly to "YES".
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Returns a `MerchantOrderStatusResponse`, whose format can differ based on the status of the payment.
   :http:statuscode:`304 Not modified`:
     The ``ETag`` in the response did not change compared to the one
     given in the ``If-none-match`` HTTP header specified by the client.
     @since protocol **v25**.
   :http:statuscode:`400 Bad Request`:
     A query parameter or HTTP header is malformed.
     Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or
     ``TALER_EC_GENERIC_HTTP_HEADERS_MALFORMED``.
   :http:statuscode:`404 Not found`:
     The order or instance is unknown to the backend. Error code
     is set to either ``TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN`` or
     ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``.
   :http:statuscode:`500 Internal Server Error`:
     The server experienced an internal failure.
     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``,
     ``TALER_EC_GENERIC_FAILED_COMPUTE_JSON_HASH``,
     ``TALER_EC_MERCHANT_GENERIC_DB_CONTRACT_CONTENT_INVALID`` or
     ``TALER_EC_MERCHANT_GET_ORDERS_ID_INVALID_CONTRACT_VERSION``.
 
   **Details:**
 
   .. ts:def:: MerchantOrderStatusResponse
 
     type MerchantOrderStatusResponse = CheckPaymentPaidResponse |
                                        CheckPaymentClaimedResponse |
                                        CheckPaymentUnpaidResponse;
 
   .. ts:def:: CheckPaymentPaidResponse
 
     interface CheckPaymentPaidResponse {
       // The customer paid for this contract.
       order_status: "paid";
 
       // Was the payment refunded (even partially)?
       refunded: boolean;
 
       // True if there are any approved refunds that the wallet has
       // not yet obtained.
       refund_pending: boolean;
 
       // Did the exchange wire us the funds?
       wired: boolean;
 
       // Total amount the exchange deposited into our bank account
       // for this contract, excluding fees.
       deposit_total: Amount;
 
       // Numeric `error code <error-codes>` indicating errors the exchange
       // encountered tracking the wire transfer for this purchase (before
       // we even got to specific coin issues).
       // 0 if there were no issues.
       exchange_code: Integer;
 
       // HTTP status code returned by the exchange when we asked for
       // information to track the wire transfer for this purchase.
       // 0 if there were no issues.
       exchange_http_status: Integer;
 
       // Total amount that was refunded, 0 if refunded is false.
       refund_amount: Amount;
 
       // Contract terms.
       contract_terms: ContractTerms;
 
       // Index of the selected choice within the ``choices`` array of
       // ``contract terms``.
       // @since protocol **v21**
       choice_index?: Integer;
 
       // If the order is paid, set to the last time when a payment
       // was made to pay for this order. @since **v14**.
       last_payment: Timestamp;
 
       // The wire transfer status from the exchange for this order if
       // available, otherwise empty array.
       wire_details: TransactionWireTransfer[];
 
       // The refund details for this order.  One entry per
       // refunded coin; empty array if there are no refunds.
       refund_details: RefundDetails[];
 
       // Refunds settled outside of Taler that were recorded for this
       // order via
       // [/instances/$INSTANCE]/private/orders/$ORDER_ID/refund-external.
       // These are bookkeeping entries only; empty array if there are
       // none.
       // @since protocol **vMixedPayments**.
       refunds_external: ExternalRefundInfo[];
 
       // Status URL, can be used as a redirect target for the browser
       // to show the order QR code / trigger the wallet.
       order_status_url: WebURL;
     }
 
   .. ts:def:: CheckPaymentClaimedResponse
 
     interface CheckPaymentClaimedResponse {
       // A wallet claimed the order, but did not yet pay for the contract.
       order_status: "claimed";
 
       // Contract terms.
       contract_terms: ContractTerms;
 
       // Status URL, can be used as a redirect target for the browser
       // to show the order QR code / trigger the wallet.
       // Since protocol **v19**.
       order_status_url: WebURL;
     }
 
   .. ts:def:: CheckPaymentUnpaidResponse
 
     interface CheckPaymentUnpaidResponse {
       // The order was not yet claimed (and thus certainly also
       // not yet paid).
       order_status: "unpaid";
 
       // URI that the wallet must process to complete the payment.
       taler_pay_uri: string;
 
       // Time when the order was created.
       creation_time: Timestamp;
 
       // Deadline when the offer expires; the customer must pay before.
       // @since protocol **v21**.
       // @deprecated in **v25** (use proto_contract_terms.pay_deadline instead).
       pay_deadline: Timestamp;
 
       // Order summary text.
       // @deprecated in **v25** (use proto_contract_terms.summary instead).
       summary: string;
 
       // We cannot return the "final" contract terms here because
       // the ``nonce`` is not available because the wallet did not yet
       // claim the order.
       // So the "ProtoContractTerms" are basically the contract terms,
       // but without the ``nonce``.
       // @since protocol **v25**.
       proto_contract_terms: ProtoContractTerms;
 
       // Total amount of the order (to be paid by the customer).
       // Will be undefined for unpaid v1 orders
       // @deprecated in **v25** (use proto_contract_terms instead).
       total_amount?: Amount;
 
       // Alternative order ID which was paid for already in the same session.
       // Only given if the same product was purchased before in the same session.
       already_paid_order_id?: Slug;
 
       // Fulfillment URL of an already paid order. Only given if under this
       // session an already paid order with a fulfillment URL exists.
       already_paid_fulfillment_url?: WebURL;
 
       // Status URL, can be used as a redirect target for the browser
       // to show the order QR code / trigger the wallet.
       order_status_url: WebURL;
 
     }
 
   .. ts:def:: RefundDetails
 
     interface RefundDetails {
       // Reason given for the refund.
       reason: string;
 
       // True if a refund is still available for the wallet for this payment.
       pending: boolean;
 
       // When was the refund approved with a POST to
       // [/instances/$INSTANCE]/private/orders/$ORDER_ID/refund
       timestamp: Timestamp;
 
       // Total amount that was refunded (minus a refund fee).
       amount: Amount;
     }
 
   .. ts:def:: ExternalRefundInfo
 
     interface ExternalRefundInfo {
       // Identifier of this refund within the order, either chosen by
       // the merchant or assigned by the backend.
       id: string;
 
       // Method by which the funds were returned to the customer,
       // for example "cash" or "card". May differ from the methods used
       // to pay the order. Never "taler".
       method: string;
 
       // The ``id`` of the ``amount_external`` entry this refund
       // reverses, when the refund maps to a specific original payment.
       payment_id?: string;
 
       // Amount returned to the customer via the external method.
       amount: Amount;
 
       // Human-readable refund justification.
       reason: string;
 
       // When the external refund was recorded at the backend.
       timestamp: Timestamp;
     }
 
   .. ts:def:: TransactionWireTransfer
 
     interface TransactionWireTransfer {
       // Responsible exchange.
       exchange_url: WebURL;
 
       // 32-byte wire transfer identifier.
       wtid: Base32;
 
       // Execution time of the wire transfer.
       execution_time: Timestamp;
 
       // Total amount that has been wire transferred
       // to the merchant from this exchange for this
       // purchase. The ``deposit_fee`` was already
       // subtracted. However, the ``wire_fee`` may still
       // apply (but not to the order, only to the aggregated transfer).
       amount: Amount;
 
       // Deposit fees to be paid to the
       // exchange for this order.
       // Since **v26**.
       deposit_fee: Amount;
 
       // Was this transfer confirmed by the merchant via the
       // POST /transfers API, or is it merely claimed by the exchange?
       confirmed: boolean;
 
       // Transfer serial ID of this wire transfer, useful as
       // ``offset`` for the GET ``/private/incoming`` endpoint.
       // Since **v25**.
       expected_transfer_serial_id: Integer;
     }
 
   .. ts:def:: TransactionWireReport
 
     interface TransactionWireReport {
       // Numerical `error code <error-codes>`.
       code: Integer;
 
       // Human-readable error description.
       hint: string;
 
       // Numerical `error code <error-codes>` from the exchange.
       exchange_code: Integer;
 
       // HTTP status code received from the exchange.
       exchange_http_status: Integer;
 
       // Public key of the coin for which we got the exchange error.
       coin_pub: CoinPublicKey;
     }