Contents

GET [/instances/$INSTANCE]/private/orders#

Returns known orders up to some point in the past.

Required permission: orders-read (see Scopes)

Request:

Accept:

The client may specify the desired MIME-type for the result. Supported are the usual “application/json”, but also “application/vnd.ms-excel”, “text/csv” and “application/pdf”.

Query Parameters:

  • paid – Optional. If set to yes, only return paid orders, if no only unpaid orders. Do not give (or use “all”) to see all orders regardless of payment status.

  • refunded – Optional. If set to yes, only return refunded orders, if no only unrefunded orders. Do not give (or use “all”) to see all orders regardless of refund status.

  • wired – Optional. If set to yes, only return wired orders, if no only orders with missing wire transfers. Do not give (or use “all”) to see all orders regardless of wire transfer status.

  • expired – Optional. If set to yes, only return expired orders, if no exclude expired orders. Do not give (or use “all”) to see all orders regardless of expiration status. An order is expired if it is unpaid and its payment deadline is strictly before the merchant backend’s current time. Paid orders are never considered expired. This filter is combined conjunctively with all other filters. Since protocol v37.

  • delta – Optional. takes value of the form N (-N), so that at most N values strictly older (younger) than start and date_s are returned. Defaults to -20 to return the last 20 entries (before start and/or date_s). Deprecated in protocol v12. Use limit instead.

  • limit – Optional. At most return the given number of results. Negative for descending by row ID, positive for ascending by row ID. Default is 20. Since protocol v12.

  • date_s – Optional. Non-negative date in seconds after the UNIX Epoc. Only return orders created after the specified timestamp.

  • max_age – Optional. Relative time in milliseconds. Only return orders younger than the specified age. Only applicable if delta is positive. If both max_age and date_s are given, the larger of the two applies. Since protocol v27. Deprecated in protocol v33. Use max_age_s instead.

  • max_age_s – Optional. Relative time in seconds. Only return orders younger than the specified age. Only applicable if limit is positive. If both max_age_s and date_s are given, the larger of the two applies. If both max_age_s and the deprecated max_age are given, max_age_s applies. Since protocol v33.

  • start – Optional. Row number threshold, see limit for its interpretation. Defaults to INT64_MAX, namely the biggest row id possible in the database. Deprecated in protocol v12. Use offset instead.

  • offset – Optional. Starting row_id for an iteration. Since protocol v12.

  • timeout_ms – Optional. Timeout in milliseconds to wait for additional orders if the answer would otherwise be negative (long polling). Only useful if limit is positive. Note that the merchant MAY still return a response that contains fewer than limit orders.

  • session_id – Optional. Since protocol v6. Filters by session ID.

  • fulfillment_url – Optional. Since protocol v6. Filters by fulfillment URL.

  • summary_filter – Optional. Only returns orders where the summary contains the given text as a substring. Matching is case-insensitive. Since protocol v23.

Response:

200 OK:

The response is an OrderHistory.

400 Bad Request:

A query parameter is malformed. Returned with TALER_EC_GENERIC_PARAMETER_MALFORMED.

401 Unauthorized:

The request is unauthorized.

404 Not found:

The instance is unknown.

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_AMOUNT, TALER_EC_MERCHANT_GENERIC_DB_CONTRACT_CONTENT_INVALID or TALER_EC_MERCHANT_GET_ORDERS_ID_INVALID_CONTRACT_VERSION.

501 Not implemented:

The requested functionality is not implemented. Usually returned if the PDF generator is not available at this backend and the requested format was application/pdf. Returned with TALER_EC_EXCHANGE_GENERIC_NO_TYPST_OR_PDFTK.

Details:

interface OrderHistory {
  // Timestamp-sorted array of all orders matching the query.
  // The order of the sorting depends on the sign of limit.
  orders : OrderHistoryEntry[];
}

interface OrderHistoryEntry {

  // Order ID of the transaction related to this entry.
  order_id: Slug;

  // Row ID of the order in the database.
  row_id: Integer;

  // When the order was created.
  timestamp: Timestamp;

  // Deadline by which the order must be paid.
  // Since protocol **v37**.
  pay_deadline: Timestamp;

  // The amount of money the order is for. If the contract
  // has multiple choices and the user has not yet made a choice,
  // we return the amount of the first choice.
  amount: Amount;

  // The total amount of refunds granted by the merchant.
  // Includes refunds that the wallet did not yet pick up.
  // Only available if the order was paid.
  // Since **v24**.
  refund_amount: Amount;

  // The amount of refunds the customer's wallet did not yet
  // pick up.  Only available if the order was paid.
  // Since **v24**.
  pending_refund_amount: Amount;

  // The summary of the order.
  summary: string;

  // Whether some part of the order is refundable,
  // that is the refund deadline has not yet expired
  // and the total amount refunded so far is below
  // the value of the original transaction.
  refundable: boolean;

  // Whether the order has been paid or not.
  paid: boolean;

  // Whether the exchange reports that it wired the order's funds.
  // This does not confirm that the merchant's bank received the transfer.
  // Since protocol **v38**.
  wired: boolean;
}
Contents