path: root/core
diff options
authorChristian Grothoff <>2020-08-12 12:14:24 +0200
committerChristian Grothoff <>2020-08-12 12:14:24 +0200
commite887347f3cb932d0b8e2852a78f6893dba39dcbd (patch)
tree7debabc10b7124c57c70d729814860a7dbfb6277 /core
parent6b8a9e91d3c17ba57ba240d45df94b712658ddd8 (diff)
improve exchange /refund spec to cover all cases
Diffstat (limited to 'core')
1 files changed, 29 insertions, 0 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 4be71fa..15547ed 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1375,10 +1375,20 @@ Refunds
The operation succeeded, the exchange confirms that the coin can now be refreshed. The response will include a `RefundSuccess` object.
:status 401 Unauthorized:
Merchant signature is invalid.
+ This response comes with a standard `ErrorDetail` response.
:status 404 Not found:
The refund operation failed as we could not find a matching deposit operation (coin, contract, transaction ID and merchant public key must all match).
+ This response comes with a standard `ErrorDetail` response.
+ :status 409 Conflict:
+ The exchange has previously received a refund request for the same coin, merchant and contract, but specifying a different amount for the same refund transaction ID. The response will be a `RefundFailure` object.
:status 410 Gone:
It is too late for a refund by the exchange, the money was already sent to the merchant.
+ This response comes with a standard `ErrorDetail` response.
+ :status 412 Precondition Failed:
+ The request transaction ID is identical to a previous refund request by the same
+ merchant for the same coin and contract, but the refund amount differs. (The
+ failed precondition is that the ``rtransaction_id`` is not unique.)
+ The response will be a `RefundFailure` object with the conflicting refund request.
@@ -1420,3 +1430,22 @@ Refunds
// which signing key was used.
exchange_pub: EddsaPublicKey;
+ .. ts:def:: RefundFailure
+ interface RefundFailure {
+ // Numeric error code unique to the condition, which can be either
+ // related to the deposit value being insufficient for the requested
+ // refund(s), or the requested refund conflicting due to refund
+ // transaction number re-use (with different amounts).
+ code: number;
+ // Human-readable description of the error message
+ hint: string;
+ // Information about the conflicting refund request(s).
+ // This will not be the full history of the coin, but only
+ // the relevant subset of the transactions.
+ history: CoinSpendHistoryItem[];
+ }