From b93b0b34ffaae3e30d13b0a134b7b2d958d97288 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 9 Apr 2020 23:42:57 +0200 Subject: specify refund API for wallets as per #5299 --- core/api-merchant.rst | 95 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 83 insertions(+), 12 deletions(-) (limited to 'core') diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 46c5dcc4..80d3b4f6 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -215,17 +215,17 @@ Giving Customer Tips the instance was never configured for tipping. :status 424 Failed Dependency: We are unable to process the request because of a problem with the exchange. - Likely returned with an "exchange-code" in addition to a "code" and - an "exchange-http-status" in addition to our own HTTP status. Also may - include the full exchange reply to our request under "exchange-reply". + Likely returned with an "exchange_code" in addition to a "code" and + an "exchange_http_status" in addition to our own HTTP status. Also may + include the full exchange reply to our request under "exchange_reply". Naturally, those diagnostics may be omitted if the exchange did not reply at all, or send a completely malformed response. :status 503 Service Unavailable: We are unable to process the request, possibly due to misconfiguration or disagreement with the exchange (it is unclear which party is to blame). - Likely returned with an "exchange-code" in addition to a "code" and - an "exchange-http-status" in addition to our own HTTP status. Also may - include the full exchange reply to our request under "exchange-reply". + Likely returned with an "exchange_code" in addition to a "code" and + an "exchange_http_status" in addition to our own HTTP status. Also may + include the full exchange reply to our request under "exchange_reply". .. ts:def:: TipCreateRequest @@ -269,17 +269,17 @@ Giving Customer Tips The merchant backend instance does not have a tipping reserve configured. :status 424 Failed Dependency: We are unable to process the request because of a problem with the exchange. - Likely returned with an "exchange-code" in addition to a "code" and - an "exchange-http-status" in addition to our own HTTP status. Also may - include the full exchange reply to our request under "exchange-reply". + Likely returned with an "exchange_code" in addition to a "code" and + an "exchange_http_status" in addition to our own HTTP status. Also may + include the full exchange reply to our request under "exchange_reply". Naturally, those diagnostics may be omitted if the exchange did not reply at all, or send a completely malformed response. :status 503 Service Unavailable: We are unable to process the request, possibly due to misconfiguration or disagreement with the exchange (it is unclear which party is to blame). - Likely returned with an "exchange-code" in addition to a "code" and - an "exchange-http-status" in addition to our own HTTP status. Also may - include the full exchange reply to our request under "exchange-reply". + Likely returned with an "exchange_code" in addition to a "code" and + an "exchange_http_status" in addition to our own HTTP status. Also may + include the full exchange reply to our request under "exchange_reply". .. ts:def:: TipQueryResponse @@ -1163,6 +1163,77 @@ both by the user's browser and their wallet. The frontend used the same order ID with different content in the order. +.. http:get:: /public/[$INSTANCE]/$ORDER/refund + + Obtain a refund issued by the merchant. + + **Response:** + + :status 200 OK: + The merchant processed the approved refund. The body is a `RefundResponse`. + Note that a successful response from the merchant does not imply that the + exchange successfully processed the refund. Clients must inspect the + body to check which coins were successfully refunded. It is possible for + only a subset of the refund request to have been processed successfully. + Re-issuing the request will cause the merchant to re-try such unsuccessful + sub-requests. + + .. ts:def:: RefundResponse + + interface RefundResponse { + // hash of the contract terms + h_contract_terms: HashCode; + + // merchant's public key + merchant_pub: EddsaPublicKey; + + // array with information about the refunds obtained + refunds: RefundDetail[]; + } + + .. ts:def:: RefundDetail + + interface RefundDetail { + + // public key of the coin to be refunded + coin_pub: EddsaPublicKey; + + // Amount approved for refund for this coin + refund_amount: Amount; + + // Refund fee the exchange will charge for the refund + refund_fee: Amount; + + // HTTP status from the exchange. 200 if successful. + exchange_http_status: integer; + + // Refund transaction ID. + rtransaction_id: integer; + + // Taler error code from the exchange. Only given if the + // exchange_http_status is not 200. + exchange_code?: integer; + + // Full exchange response. Only given if the + // exchange_http_status is not 200 and the exchange + // did return JSON. + exchange_reply?: integer; + + // Public key of the exchange used for the exchange_sig. + // Only given if the exchange_http_status is 200. + exchange_pub?: EddsaPublicKey; + + // Signature the exchange confirming the refund. + // Only given if the exchange_http_status is 200. + exchange_sig?: EddsaSignature; + + } + + :status 404 Not found: + The merchant is unaware of having granted a refund, or even of + the order specified. + + .. http:post:: /public/tip-pickup Handle request from wallet to pick up a tip. -- cgit v1.2.3