diff options
Diffstat (limited to 'src/include/taler_exchange_service.h')
| -rw-r--r-- | src/include/taler_exchange_service.h | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/src/include/taler_exchange_service.h b/src/include/taler_exchange_service.h index ffd420586..2f9a1932c 100644 --- a/src/include/taler_exchange_service.h +++ b/src/include/taler_exchange_service.h @@ -465,6 +465,83 @@ void TALER_EXCHANGE_deposit_cancel (struct TALER_EXCHANGE_DepositHandle *deposit); +/* ********************* /refund *********************** */ + +/** + * @brief A Refund Handle + */ +struct TALER_EXCHANGE_RefundHandle; + + +/** + * Callbacks of this type are used to serve the result of submitting a + * deposit permission request to a exchange. + * + * @param cls closure + * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful deposit; + * 0 if the exchange's reply is bogus (fails to follow the protocol) + * @param obj the received JSON reply, should be kept as proof (and, in particular, + * be forwarded to the customer) + */ +typedef void +(*TALER_EXCHANGE_RefundResultCallback) (void *cls, + unsigned int http_status, + const json_t *obj); + + +/** + * Submit a refund request to the exchange and get the exchange's + * response. This API is used by a merchant. Note that + * while we return the response verbatim to the caller for further + * processing, we do already verify that the response is well-formed + * (i.e. that signatures included in the response are all valid). If + * the exchange's reply is not well-formed, we return an HTTP status code + * of zero to @a cb. + * + * The @a exchange must be ready to operate (i.e. have + * finished processing the /keys reply). If this check fails, we do + * NOT initiate the transaction with the exchange and instead return NULL. + * + * @param exchange the exchange handle; the exchange must be ready to operate + * @param amount the amount to be refunded; must be larger than the refund fee + * (as that fee is still being subtracted), and smaller than the amount + * (with deposit fee) of the original deposit contribution of this coin + * @param h_contract hash of the contact of the merchant with the customer that is being refunded + * @param transaction_id transaction id for the transaction being refunded, must match @a h_contract + * @param coin_pub coin’s public key of the coin from the original deposit operation + * @param rtransaction_id transaction id for the transaction between merchant and customer (of refunding operation); + * this is needed as we may first do a partial refund and later a full refund. If both + * refunds are also over the same amount, we need the @a rtransaction_id to make the disjoint + * refund requests different (as requests are idempotent and otherwise the 2nd refund might not work). + * @param merchant_priv the private key of the merchant, used to generate signature for refund request + * @param cb the callback to call when a reply for this request is available + * @param cb_cls closure for the above callback + * @return a handle for this request; NULL if the inputs are invalid (i.e. + * signatures fail to verify). In this case, the callback is not called. + */ +struct TALER_EXCHANGE_RefundHandle * +TALER_EXCHANGE_refund (struct TALER_EXCHANGE_Handle *exchange, + const struct TALER_Amount *amount, + const struct GNUNET_HashCode *h_contract, + const struct TALER_CoinSpendPublicKeyP *coin_pub, + uint64_t rtransaction_id, + const struct TALER_MerchantPrivateKeyP *merchant_priv, + TALER_EXCHANGE_RefundResultCallback cb, + void *cb_cls); + + +/** + * Cancel a refund permission request. This function cannot be used + * on a request handle if a response is already served for it. If + * this function is called, the refund may or may not have happened. + * However, it is fine to try to refund the coin a second time. + * + * @param refund the refund request handle + */ +void +TALER_EXCHANGE_refund_cancel (struct TALER_EXCHANGE_RefundHandle *refund); + + /* ********************* /reserve/status *********************** */ |