specify claim tokens

2 files changed, 28 insertions, 4 deletions

diff --git a/core/api-common.rst b/core/api-common.rst
index 987ba664..ed799e96 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -200,10 +200,11 @@ but also decodes to "V" to make OCR easy.  We will still simply use the JSON
 type "base32" and the term "Crockford Base32" in the text to refer to the
 resulting encoding.
 
+
 Hash codes
 ^^^^^^^^^^
-Hash codes are strings representing base32 encoding of the respective hashed
-data. See `base32`_.
+Hash codes are strings representing base32 encoding of the respective
+hashed data. See `base32`_.
 
 .. ts:def:: HashCode
 
@@ -213,7 +214,8 @@ data. See `base32`_.
 .. ts:def:: ShortHashCode
 
   // 32-byte hash code
-  type HashCode = string;
+  type ShortHashCode = string;
+
 
 Safe Integers
 ^^^^^^^^^^^^^
@@ -278,6 +280,11 @@ Objects
 Keys
 ^^^^
 
+.. ts:def:: ClaimToken
+
+  // 16-byte access token used to authorize access
+  type ClaimToken = string;
+
 .. ts:def:: EddsaPublicKey
 
    // EdDSA and ECDHE public keys always point on Curve25519
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 24936086..25cee222 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -693,6 +693,12 @@ Payment processing
       // shopping sessions that were combined during checkout).
       lock_uuids?: UUID[];
 
+      // Should a token for claiming the order be generated?
+      // False can make sense if the ORDER_ID is sufficiently
+      // high entropy to prevent adversarial claims (like it is
+      // if the backend auto-generates one).
+      create_token: boolean;
+
     }
 
   .. ts:def:: Order
@@ -749,6 +755,11 @@ Payment processing
     interface PostOrderResponse {
       // Order ID of the response that was just created
       order_id: string;
+
+      // Token that authorizes the wallet to claim the order.
+      // Provided only if "create_token" was set to 'true'
+      // in the request.
+      token?: ClaimToken;
     }
 
 
@@ -848,6 +859,11 @@ Payment processing
     interface ClaimRequest {
       // Nonce to identify the wallet that claimed the order.
       nonce: string;
+
+      // Token that authorizes the wallet to claim the order.
+      // *Optional* as the merchant may not have required it
+      // (``create_token`` set to ``false`` in `PostOrderRequest`).
+      token?: ClaimToken;
     }
 
   **Response:**
@@ -1359,7 +1375,8 @@ Payment processing
 
   **Request:**
 
-  :query h_contract: hash of the order's contract terms (this is used to authenticate the wallet/customer in case $ORDER_ID is guessable). *Mandatory!*
+  :query h_contract: hash of the order's contract terms (this is used to authenticate the wallet/customer in case $ORDER_ID is guessable). Either this field or *token* is *mandatory*.
+  :query token=TOKEN: *Optional*. Authorizes the request via the claim token that was returned  in the `PostOrderResponse`.  Either this field or *h_contract* is *mandatory*.
   :query session_id: *Optional*. Session ID that the payment must be bound to.  If not specified, the payment is not session-bound.
   :query timeout_ms: *Optional.*  If specified, the merchant backend will
     wait up to ``timeout_ms`` milliseconds for completion of the payment before