From e887347f3cb932d0b8e2852a78f6893dba39dcbd Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 12 Aug 2020 12:14:24 +0200 Subject: improve exchange /refund spec to cover all cases --- core/api-exchange.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'core/api-exchange.rst') diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 4be71fa6..15547ed5 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. **Details:** @@ -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[]; + } -- cgit v1.2.3