post-coins-COIN_PUB-refund.rst (3699B)
1 .. http:post:: /coins/$COIN_PUB/refund 2 3 Undo deposit of the given coin, restoring its value. 4 5 **Request:** 6 7 The request body must be a `RefundRequest` object. 8 9 **Response:** 10 11 :http:statuscode:`200 OK`: 12 The operation succeeded, the exchange confirms that the coin can now be refreshed. The response will include a `RefundSuccess` object. 13 :http:statuscode:`403 Forbidden`: 14 Merchant signature is invalid. 15 This response comes with a standard `ErrorDetail` response. 16 :http:statuscode:`404 Not found`: 17 The refund operation failed as we could not find a matching deposit operation (coin, contract, transaction ID and merchant public key must all match). 18 This response comes with a standard `ErrorDetail` response. 19 :http:statuscode:`409 Conflict`: 20 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. 21 :http:statuscode:`410 Gone`: 22 It is too late for a refund by the exchange, the money was already sent to the merchant. 23 This response comes with a standard `ErrorDetail` response. 24 :http:statuscode:`412 Precondition failed`: 25 The request transaction ID is identical to a previous refund request by the same 26 merchant for the same coin and contract, but the refund amount differs. (The 27 failed precondition is that the ``rtransaction_id`` is not unique.) 28 The response will be a `RefundFailure` object with the conflicting refund request. 29 30 **Details:** 31 32 .. ts:def:: RefundRequest 33 34 interface RefundRequest { 35 36 // Amount to be refunded, can be a fraction of the 37 // coin's total deposit value (including deposit fee); 38 // must be larger than the refund fee. 39 refund_amount: Amount; 40 41 // SHA-512 hash of the contact of the merchant with the customer. 42 h_contract_terms: HashCode; 43 44 // 64-bit transaction id of the refund transaction between merchant and customer. 45 rtransaction_id: Integer; 46 47 // EdDSA public key of the merchant. 48 merchant_pub: EddsaPublicKey; 49 50 // EdDSA signature of the merchant over a 51 // `TALER_RefundRequestPS` with purpose 52 // ``TALER_SIGNATURE_MERCHANT_REFUND`` 53 // affirming the refund. 54 merchant_sig: EddsaPublicKey; 55 56 } 57 58 .. ts:def:: RefundSuccess 59 60 interface RefundSuccess { 61 62 // The EdDSA :ref:`signature` (binary-only) with purpose 63 // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND`` over 64 // a `TALER_RecoupRefreshConfirmationPS` 65 // using a current signing key of the 66 // exchange affirming the successful refund. 67 exchange_sig: EddsaSignature; 68 69 // Public EdDSA key of the exchange that was used to generate the signature. 70 // Should match one of the exchange's signing keys from ``/keys``. It is given 71 // explicitly as the client might otherwise be confused by clock skew as to 72 // which signing key was used. 73 exchange_pub: EddsaPublicKey; 74 } 75 76 .. ts:def:: RefundFailure 77 78 interface RefundFailure { 79 80 // Numeric error code unique to the condition, which can be either 81 // related to the deposit value being insufficient for the requested 82 // refund(s), or the requested refund conflicting due to refund 83 // transaction number re-use (with different amounts). 84 code: Integer; 85 86 // Human-readable description of the error message. 87 hint: string; 88 89 // Information about the conflicting refund request(s). 90 // This will not be the full history of the coin, but only 91 // the relevant subset of the transactions. 92 history: CoinSpendHistoryItem[]; 93 }