post-orders-ORDER_ID-refund.h (5295B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Lesser General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. 12 13 You should have received a copy of the GNU Lesser General Public License along with 14 TALER; see the file COPYING.LGPL. If not, see 15 <http://www.gnu.org/licenses/> 16 */ 17 /** 18 * @file src/include/taler/merchant/post-orders-ORDER_ID-refund.h 19 * @brief C interface for the POST /orders/$ORDER_ID/refund endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_ORDERS_ORDER_ID_REFUND_H 23 #define _TALER_MERCHANT__POST_ORDERS_ORDER_ID_REFUND_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Handle for a POST /orders/$ORDER_ID/refund request. 30 */ 31 struct TALER_MERCHANT_PostOrdersRefundHandle; 32 33 34 /** 35 * Details about one refund from the exchange. 36 */ 37 struct TALER_MERCHANT_PostOrdersRefundDetail 38 { 39 40 /** 41 * Exchange signature confirming the refund. 42 */ 43 struct TALER_ExchangeSignatureP exchange_sig; 44 45 /** 46 * Exchange public key used for @e exchange_sig. 47 */ 48 struct TALER_ExchangePublicKeyP exchange_pub; 49 50 /** 51 * Hash of the contract terms. 52 */ 53 struct TALER_PrivateContractHashP h_contract_terms; 54 55 /** 56 * Merchant public key. 57 */ 58 struct TALER_MerchantPublicKeyP merchant_pub; 59 60 /** 61 * Refund transaction ID. 62 */ 63 uint64_t rtransaction_id; 64 65 /** 66 * Public key of the refunded coin. 67 */ 68 struct TALER_CoinSpendPublicKeyP coin_pub; 69 70 /** 71 * Refund amount. 72 */ 73 struct TALER_Amount refund_amount; 74 75 /** 76 * Refund fee charged by the exchange. 77 */ 78 struct TALER_Amount refund_fee; 79 80 /** 81 * HTTP status returned by the exchange for this refund, 0 if not yet 82 * obtained. 83 */ 84 unsigned int exchange_http_status; 85 86 /** 87 * Taler error code returned by the exchange. 88 */ 89 enum TALER_ErrorCode ec; 90 91 /** 92 * Full exchange reply (JSON), or NULL. 93 */ 94 const json_t *exchange_reply; 95 96 /** 97 * HTTP response details from the exchange. 98 */ 99 struct TALER_MERCHANT_HttpResponse hr; 100 101 }; 102 103 104 /** 105 * Response details for a POST /orders/$ORDER_ID/refund request. 106 */ 107 struct TALER_MERCHANT_PostOrdersRefundResponse 108 { 109 110 /** 111 * HTTP response details. 112 */ 113 struct TALER_MERCHANT_HttpResponse hr; 114 115 /** 116 * Details depending on the HTTP status code. 117 */ 118 union 119 { 120 121 /** 122 * Details on #MHD_HTTP_OK. 123 */ 124 struct 125 { 126 127 /** 128 * Number of refund details in @a refunds. 129 */ 130 unsigned int num_refunds; 131 132 /** 133 * Array of refund details. 134 */ 135 const struct TALER_MERCHANT_PostOrdersRefundDetail *refunds; 136 137 /** 138 * Total effective refund amount. 139 */ 140 struct TALER_Amount refund_amount; 141 142 /** 143 * Merchant public key. 144 */ 145 struct TALER_MerchantPublicKeyP merchant_pub; 146 147 } ok; 148 149 } details; 150 151 }; 152 153 154 /** 155 * Set up POST /orders/$ORDER_ID/refund operation. 156 * Note that you must explicitly start the operation after 157 * possibly setting options. 158 * 159 * @param ctx the context 160 * @param url base URL of the merchant backend 161 * @param order_id identifier of the order 162 * @param h_contract_terms hash of the contract terms 163 * @return handle to operation 164 */ 165 struct TALER_MERCHANT_PostOrdersRefundHandle * 166 TALER_MERCHANT_post_orders_refund_create ( 167 struct GNUNET_CURL_Context *ctx, 168 const char *url, 169 const char *order_id, 170 const struct TALER_PrivateContractHashP *h_contract_terms); 171 172 173 #ifndef TALER_MERCHANT_POST_ORDERS_REFUND_RESULT_CLOSURE 174 /** 175 * Type of the closure used by 176 * the #TALER_MERCHANT_PostOrdersRefundCallback. 177 */ 178 #define TALER_MERCHANT_POST_ORDERS_REFUND_RESULT_CLOSURE void 179 #endif /* TALER_MERCHANT_POST_ORDERS_REFUND_RESULT_CLOSURE */ 180 181 /** 182 * Callback for a POST /orders/$ORDER_ID/refund request. 183 * 184 * @param cls closure 185 * @param orr response details 186 */ 187 typedef void 188 (*TALER_MERCHANT_PostOrdersRefundCallback)( 189 TALER_MERCHANT_POST_ORDERS_REFUND_RESULT_CLOSURE *cls, 190 const struct TALER_MERCHANT_PostOrdersRefundResponse *orr); 191 192 193 /** 194 * Start POST /orders/$ORDER_ID/refund operation. 195 * 196 * @param[in,out] porh operation to start 197 * @param cb function to call with the merchant's result 198 * @param cb_cls closure for @a cb 199 * @return status code, #TALER_EC_NONE on success 200 */ 201 enum TALER_ErrorCode 202 TALER_MERCHANT_post_orders_refund_start ( 203 struct TALER_MERCHANT_PostOrdersRefundHandle *porh, 204 TALER_MERCHANT_PostOrdersRefundCallback cb, 205 TALER_MERCHANT_POST_ORDERS_REFUND_RESULT_CLOSURE *cb_cls); 206 207 208 /** 209 * Cancel POST /orders/$ORDER_ID/refund operation. This function must not be 210 * called by clients after the TALER_MERCHANT_PostOrdersRefundCallback has 211 * been invoked (as in those cases it'll be called internally by the 212 * implementation already). 213 * 214 * @param[in] porh operation to cancel 215 */ 216 void 217 TALER_MERCHANT_post_orders_refund_cancel ( 218 struct TALER_MERCHANT_PostOrdersRefundHandle *porh); 219 220 221 #endif /* _TALER_MERCHANT__POST_ORDERS_ORDER_ID_REFUND_H */