From b86bb3377a8052e3a88645287311ce1dd39bc8c5 Mon Sep 17 00:00:00 2001 From: Jonathan Buchanan Date: Fri, 14 Aug 2020 20:57:54 -0400 Subject: add merchant POST /orders/$ORDER_ID/refund --- core/api-merchant.rst | 170 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 101 insertions(+), 69 deletions(-) (limited to 'core') diff --git a/core/api-merchant.rst b/core/api-merchant.rst index db1bf9cb..cff71d04 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -1428,9 +1428,6 @@ Payment processing // Amount that was refunded in total. refund_amount: Amount; - // Successful refunds for this payment, empty array for none. - refunds: MerchantCoinRefundStatus[]; - // Public key of the merchant. merchant_pub: EddsaPublicKey; @@ -1458,6 +1455,106 @@ Payment processing fulfillment_url: string; } + +.. http:delete:: /private/orders/$ORDER_ID + + Delete information about an order. Fails if the order was paid in the + last 10 years (or whatever TAX_RECORD_EXPIRATION is set to) or was + claimed but is unpaid and thus still a valid offer. + + **Response:** + + :status 204 No content: + The backend has successfully deleted the order. + :status 404 Not found: + The backend does not know the instance or the order. + :status 409 Conflict: + The backend refuses to delete the order. + + +.. _merchant_refund: + +-------------- +Giving Refunds +-------------- + +.. http:post:: /private/orders/$ORDER_ID/refund + + Increase the refund amount associated with a given order. The user should be + redirected to the ``taler_refund_uri`` to trigger refund processing in the wallet. + + **Request:** + + The request body is a `RefundRequest` object. + + **Response:** + + :status 200 OK: + The refund amount has been increased, the backend responds with a `MerchantRefundResponse` + :status 404 Not found: + The order is unknown to the merchant + :status 410 Gone: + It is too late for aborting, the exchange may have already wired the funds + to the merchant. + :status 409 Conflict: + The refund amount exceeds the amount originally paid + + .. ts:def:: RefundRequest + + interface RefundRequest { + // Amount to be refunded + refund: Amount; + + // Human-readable refund justification + reason: string; + } + + .. ts:def:: MerchantRefundResponse + + interface MerchantRefundResponse { + + // URL (handled by the backend) that the wallet should access to + // trigger refund processing. + // taler://refund/[$H_CONTRACT/$AMOUNT????] + taler_refund_uri: string; + } + + +.. http:post:: /orders/$ORDER_ID/refund + + Obtain refunds for an order. After talking to the exchange, the refunds will + no longer be pending if processed successfully. + + **Request:** + + :query h_contract=HASH: hash of the order's contract terms (this is used to authenticate the wallet/customer in case $ORDER_ID is guessable). Required. + + **Response:** + + :status 200 OK: + The response is a `WalletRefundResponse`. + :status 403 Forbidden: + The ``h_contract`` does not match the order. + :status 404 Not found: + The merchant backend is unaware of the order. + + .. ts:def:: WalletRefundResponse + + interface WalletRefundResponse { + // Was the payment refunded (even partially, via refund or abort)? + refunded: boolean; + + // Amount that was refunded in total. + refund_amount: Amount; + + // Successful refunds for this payment, empty array for none. + refunds: MerchantCoinRefundStatus[]; + + // Public key of the merchant. + merchant_pub: EddsaPublicKey; + + } + .. ts:def:: MerchantCoinRefundStatus type MerchantCoinRefundStatus = @@ -1497,7 +1594,7 @@ Payment processing // Additional details needed to verify the refund confirmation signature // (``h_contract_terms`` and ``merchant_pub``) are already known // to the wallet and thus not included. - interface RefundConfirmation { + interface MerchantCoinRefundSuccessStatus { // Used as tag for the sum type MerchantCoinRefundStatus sum type. type: "success"; @@ -1528,71 +1625,6 @@ Payment processing } -.. http:delete:: /private/orders/$ORDER_ID - - Delete information about an order. Fails if the order was paid in the - last 10 years (or whatever TAX_RECORD_EXPIRATION is set to) or was - claimed but is unpaid and thus still a valid offer. - - **Response:** - - :status 204 No content: - The backend has successfully deleted the order. - :status 404 Not found: - The backend does not know the instance or the order. - :status 409 Conflict: - The backend refuses to delete the order. - - -.. _merchant_refund: - --------------- -Giving Refunds --------------- - -.. http:post:: /private/orders/$ORDER_ID/refund - - Increase the refund amount associated with a given order. The user should be - redirected to the ``taler_refund_uri`` to trigger refund processing in the wallet. - - **Request:** - - The request body is a `RefundRequest` object. - - **Response:** - - :status 200 OK: - The refund amount has been increased, the backend responds with a `MerchantRefundResponse` - :status 404 Not found: - The order is unknown to the merchant - :status 410 Gone: - It is too late for aborting, the exchange may have already wired the funds - to the merchant. - :status 409 Conflict: - The refund amount exceeds the amount originally paid - - .. ts:def:: RefundRequest - - interface RefundRequest { - // Amount to be refunded - refund: Amount; - - // Human-readable refund justification - reason: string; - } - - .. ts:def:: MerchantRefundResponse - - interface MerchantRefundResponse { - - // URL (handled by the backend) that the wallet should access to - // trigger refund processing. - // taler://refund/[$H_CONTRACT/$AMOUNT????] - taler_refund_uri: string; - } - - - ------------------------ Tracking Wire Transfers ------------------------ -- cgit v1.2.3