POST [/instances/$INSTANCE]/orders/$ORDER_ID/refund

Obtain refunds for an order. After talking to the exchange, the refunds will no longer be pending if processed successfully.

Request:

The request body is a WalletRefundRequest object.

Response:

200 OK:

The response is a WalletRefundResponse.

204 No content:

There are no refunds for the order.

403 Forbidden:

The h_contract does not match the order.

404 Not found:

The merchant backend is unaware of the order.

410 Gone:

The wire deadline has past and it is too late to grant a refund. Since protocol v24.

Details:

interface WalletRefundRequest {
  // Hash of the order's contract terms (this is used to authenticate the
  // wallet/customer).
  h_contract: HashCode;
}

interface WalletRefundResponse {
  // Amount that was refunded in total.
  refund_amount: Amount;

  // Successful refunds for this payment, empty array for none.
  refunds: MerchantCoinRefundStatus[];

  // Public key of the merchant.
  merchant_pub: EddsaPublicKey;

}

type MerchantCoinRefundStatus =
  | MerchantCoinRefundSuccessStatus
  | MerchantCoinRefundFailureStatus;

// Details about why a refund failed.
interface MerchantCoinRefundFailureStatus {
  // Used as tag for the sum type RefundStatus sum type.
  type: "failure";

  // HTTP status of the exchange request, must NOT be 200.
  exchange_status: Integer;

  // Taler error code from the exchange reply, if available.
  exchange_code?: Integer;

  // If available, HTTP reply from the exchange.
  exchange_reply?: Object;

  // Refund transaction ID.
  rtransaction_id: Integer;

  // Public key of a coin that was refunded.
  coin_pub: EddsaPublicKey;

  // Amount that was refunded, including refund fee charged by the exchange
  // to the customer.
  refund_amount: Amount;

  // Timestamp when the merchant approved the refund.
  // Useful for grouping refunds.
  execution_time: Timestamp;
}

// Additional details needed to verify the refund confirmation signature
// (h_contract_terms and merchant_pub) are already known
// to the wallet and thus not included.
interface MerchantCoinRefundSuccessStatus {
  // Used as tag for the sum type MerchantCoinRefundStatus sum type.
  type: "success";

  // HTTP status of the exchange request, 200 (integer) required for refund confirmations.
  exchange_status: 200;

  // The EdDSA :ref:signature (binary-only) with purpose
  // TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND using a current signing key of the
  // exchange affirming the successful refund.
  exchange_sig: EddsaSignature;

  // Public EdDSA key of the exchange that was used to generate the signature.
  // Should match one of the exchange's signing keys from /keys.  It is given
  // explicitly as the client might otherwise be confused by clock skew as to
  // which signing key was used.
  exchange_pub: EddsaPublicKey;

  // Refund transaction ID.
  rtransaction_id: Integer;

  // Public key of a coin that was refunded.
  coin_pub: EddsaPublicKey;

  // Amount that was refunded, including refund fee charged by the exchange
  // to the customer.
  refund_amount: Amount;

  // Timestamp when the merchant approved the refund.
  // Useful for grouping refunds.
  execution_time: Timestamp;
}