GET [/instances/$INSTANCE]/orders/$ORDER_ID

Query the payment status of an order. This endpoint is for the wallet and possibly for Web shops and other integrations that need an unauthenticated way to query the order status (like when checking it from JavaScript from inside the customer’s browser). It is also possible to just redirect a browser to this URL to initiate the payment process.

When a client (usually a wallet) goes to this URL and it is unpaid, it will be prompted for payment. This endpoint typically also supports requests with the “Accept” header requesting “text/html”. In this case, an HTML response suitable for triggering the interaction with the wallet is returned, with timeout_ms ignored (treated as zero). If the backend installation does not include the required HTML templates, a 406 status code is returned.

In the case that the request was made with a claim token (even the wrong one) and the order was claimed and paid, the server will redirect the client to the fulfillment URL. This redirection will happen with a 302 status code if the “Accept” header specified “text/html”, and with a 202 status code otherwise.

Request:

Query Parameters:

• h_contract=HASH – Optional. Hash of the order’s contract terms (this is used to authenticate the wallet/customer in case $ORDER_ID is guessable). Required once an order was claimed.

• token=TOKEN – Optional. Authorizes the request via the claim token that was returned in the PostOrderResponse. Used with unclaimed orders only. Whether token authorization is required is determined by the merchant when the frontend creates the order.

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

• timeout_ms=NUMBER – Optional. If specified, the merchant backend will wait up to timeout_ms milliseconds for completion of the payment before sending the HTTP response. A client must never rely on this behavior, as the merchant backend may return a response immediately.

• await_refund_obtained=BOOLEAN – Optional. If set to “yes”, poll for the order’s pending refunds to be picked up. timeout_ms specifies how long we will wait for the refund.

• refund=AMOUNT – Optional. Indicates that we are polling for a refund above the given AMOUNT. timeout_ms will specify how long we will wait for the refund.

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

The response is a StatusPaidResponse.

202 Accepted:

The response is a StatusGotoResponse. Returned only for unauthenticated (no nonce, no contract hash) requests and only if the order was claimed already. Only returned if the content type requested was not HTML, if HTML was requested a 302 Found will be returned instead. The target site may allow the client to setup a fresh order (as this one has been taken) or may trigger repurchase detection. Note that if the contract lacks a public_reorder_url the backend will instead return a 403 Forbidden response.

302 Found:

The client should go to the indicated location (via HTTP “Location:” header). Returned only for unauthenticated (no nonce, no contract hash) requests and only if the order was claimed already. Only returned if the content type requested was HTML if HTML was not requested a 302 Accepted will be returned instead. The target site may allow the client to setup a fresh order (as this one has been taken) or may trigger repurchase detection. Note that if the contract lacks a public_reorder_url the backend will instead return a 403 Forbidden response.

402 Payment required:

The response is a StatusUnpaidResponse.

403 Forbidden:

The h_contract (or the token for unclaimed orders) does not match the order and we have no fulfillment URL in the contract.

404 Not found:

The merchant backend is unaware of the order.

406 Not acceptable:

The merchant backend could not load the template required to generate a reply in the desired format. (Likely HTML templates were not properly installed.)

Details:

interface StatusPaidResponse {
  // Was the payment refunded (even partially, via refund or abort)?
  refunded: boolean;

  // Is any amount of the refund still waiting to be picked up (even partially)?
  refund_pending: boolean;

  // Amount that was refunded in total.
  refund_amount: Amount;

  // Amount that already taken by the wallet.
  refund_taken: Amount;
}

interface StatusGotoResponse {
  // The client should go to the reorder URL, there a fresh
  // order might be created as this one is taken by another
  // customer or wallet (or repurchase detection logic may
  // apply).
  public_reorder_url: string;
}

interface StatusUnpaidResponse {
  // URI that the wallet must process to complete the payment.
  taler_pay_uri: string;

  // Fulfillment URL of the contract.
  // If present, it should be possible to create an
  // equivalent order by redirecting a browser to this
  // URL. Once the customer has paid, they should see the
  // order's fulfillment (digital goods, tracking data for
  // shipping, etc.) under this URL (assuming they use the
  // same session that the wallet used when making the payment).
  fulfillment_url?: string;

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