From ece354edbceb6a8708642c4f1a55ac6af8b56231 Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Sat, 18 Jul 2020 21:43:03 +0200
Subject: specify /paid request for #5210

---
 core/api-merchant.rst | 49 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

(limited to 'core/api-merchant.rst')

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 8e86c61f..1dcdfbb7 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -860,7 +860,8 @@ Payment processing
   :status 200 OK:
     The exchange accepted all of the coins.
     The body is a `payment response <PaymentResponse>`.
-    The ``frontend`` should now fullfill the contract.
+    The ``frontend`` should now fulfill the contract.
+    Note that it is possible that refunds have been granted.
   :status 400 Bad request:
     Either the client request is malformed or some specific processing error
     happened that may be the fault of the client as detailed in the JSON body
@@ -943,6 +944,52 @@ Payment processing
       exchange_url: string;
     }
 
+
+.. http:post:: /orders/$ORDER_ID/paid
+
+  Proof that the client previously paid for an order by providing
+  the merchant's signature from the `payment response <PaymentResponse>`.
+  Typically used by the customer's wallet if it receives a request for
+  payment for an order that it already paid. This is more compact then
+  re-transmitting the full payment details.
+  Note that this request does include the
+  usual ``h_contract`` argument to authenticate the wallet and
+  to allow the merchant to verify the signature before checking
+  with its own database. 
+
+  **Request:**
+
+  The request must be a `paid request <PaidRequest>`.
+
+  **Response:**
+
+  :status 204 No content:
+    The merchant accepted the signature.
+    The ``frontend`` should now fulfill the contract.
+    Note that it is possible that refunds have been granted.
+  :status 400 Bad request:
+    Either the client request is malformed or some specific processing error
+    happened that may be the fault of the client as detailed in the JSON body
+    of the response.
+  :status 403 Forbidden:
+    The signature was not valid.
+  :status 404 Not found:
+    The merchant backend could not find the order or the instance
+    and thus cannot process the request.
+
+  .. ts:def:: PaidRequest
+
+    interface PaidRequest {
+      // Signature on ``TALER_PaymentResponsePS`` with the public
+      // key of the merchant instance.
+      sig: EddsaSignature;
+
+      // hash of the order's contract terms (this is used to authenticate the
+      // wallet/customer and to enable signature verification without
+      // database access).
+      h_contract: HashCode;
+    }
+
 .. _order-abort:
 .. http:post:: /orders/$ORDER_ID/abort
 
-- 
cgit v1.2.3