summaryrefslogtreecommitdiff
path: root/core
diff options
context:
space:
mode:
authorJonathan Buchanan <jonathan.russ.buchanan@gmail.com>2020-08-14 20:57:54 -0400
committerJonathan Buchanan <jonathan.russ.buchanan@gmail.com>2020-08-14 20:58:52 -0400
commitb86bb3377a8052e3a88645287311ce1dd39bc8c5 (patch)
tree9c0a8fd56535e3b79cc42559649bd43225bb6a6a /core
parent8fef03b7aaa3ab9da1a997574ec85d473f18722c (diff)
downloaddocs-b86bb3377a8052e3a88645287311ce1dd39bc8c5.tar.gz
docs-b86bb3377a8052e3a88645287311ce1dd39bc8c5.tar.bz2
docs-b86bb3377a8052e3a88645287311ce1dd39bc8c5.zip
add merchant POST /orders/$ORDER_ID/refund
Diffstat (limited to 'core')
-rw-r--r--core/api-merchant.rst170
1 files changed, 101 insertions, 69 deletions
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index db1bf9c..cff71d0 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
------------------------