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

Increase the refund amount associated with a given order. The user should be redirected to the taler_refund_uri to trigger refund processing in the wallet.

Since vMixedPayments. For orders with refunds settled through external payment methods, the cumulative Taler refund must not exceed the full order total minus those external refunds.

Required permission: orders-refund (see Scopes)

Request:

The request body is a RefundRequest object.

Response:

200 OK:

The refund amount has been increased, the backend responds with a MerchantRefundResponse.

400 Bad Request:

The request body is malformed.

403 Forbidden:

For the given order, the refund delay was zero and thus refunds are categorically not allowed. Returned with TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_NOT_ALLOWED_BY_CONTRACT.

404 Not found:

The order is unknown to the merchant. Returned with TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN.

409 Conflict:

The refund amount exceeds the amount originally paid, the combined Taler and external refunds would exceed the full order total (since vMixedPayments), or the order was not yet paid. Returned with TALER_EC_MERCHANT_GENERIC_CURRENCY_MISMATCH or TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_ORDER_UNPAID, TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_INCONSISTENT_AMOUNT (since vMixedPayments).

410 Gone:

It is too late for refunds, the exchange may have already wired the funds to the merchant. Returned with TALER_EC_MERCHANT_PRIVATE_POST_REFUND_AFTER_WIRE_DEADLINE.

451 Unavailable for Legal Reasons:

The refund could not be awarded because of legal reasons (an exchange would refuse). The merchant staff needs to find another way to give a refund to the customer. The body is an ErrorDetail with an error code of TALER_EC_MERCHANT_POST_ORDERS_ID_REFUND_EXCHANGE_TRANSACTION_LIMIT_VIOLATION.

500 Internal Server Error:

The server experienced an internal failure. Returned with TALER_EC_GENERIC_DB_START_FAILED, TALER_EC_GENERIC_DB_FETCH_FAILED, TALER_EC_GENERIC_DB_COMMIT_FAILED, TALER_EC_GENERIC_DB_INVARIANT_FAILURE, TALER_EC_GENERIC_FAILED_COMPUTE_JSON_HASH or TALER_EC_MERCHANT_GENERIC_DB_CONTRACT_CONTENT_INVALID.

Details:

interface RefundRequest {
  // Amount to be refunded.
  refund: Amount;

  // Human-readable refund justification.
  reason: string;
}

interface MerchantRefundResponse {

  // URL (handled by the backend) that the wallet should access to
  // trigger refund processing.
  // taler://refund/...
  taler_refund_uri: string;

  // Contract hash that a client may need to authenticate an
  // HTTP request to obtain the above URI in a wallet-friendly way.
  h_contract: HashCode;
}