Contents

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

Request:

Query Parameters:

  • session_id – Optional. Session ID that the payment must be bound to. If not specified, the payment is not session-bound.

  • 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.

  • timeout_ms – Optional. Timeout in milliseconds to wait for a payment if the answer would otherwise be negative (long polling).

  • 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.

  • 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:

200 OK:

Returns a MerchantOrderStatusResponse, whose format can differ based on the status of the payment.

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.

404 Not found:

The order or instance is unknown to the backend. Error code is set to either MERCHANT_GENERIC_ORDER_UNKNOWN or MERCHANT_GENERIC_INSTANCE_UNKNOWN.

Details:

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 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[];

  // Groups about trouble obtaining wire transfer details,
  // empty array if no trouble were encountered.
  // @deprecated in protocol **v6**.
  wire_groups: TransactionWireReport[];

  // The refund details for this order.  One entry per
  // refunded coin; empty array if there are no refunds.
  refund_details: RefundDetails[];

  // Status URL, can be used as a redirect target for the browser
  // to show the order QR code / trigger the wallet.
  order_status_url: string;
}

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: string;
}

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?: string;

  // 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?: string;

  // Status URL, can be used as a redirect target for the browser
  // to show the order QR code / trigger the wallet.
  order_status_url: string;

}

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;
}

interface TransactionWireTransfer {
  // Responsible exchange.
  exchange_url: string;

  // 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;
}

interface TransactionWireReport {
  // Numerical error code.
  code: Integer;

  // Human-readable error description.
  hint: string;

  // Numerical error code 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;
}
Contents