[taler-docs] branch master updated: specify claim tokens

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new e15e209  specify claim tokens
     new 0ad320c  Merge branch 'master' of git+ssh://git.taler.net/docs
e15e209 is described below

commit e15e209e76e7970c73b4e359dba2196ffc9b9c6d
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Mon Jul 27 10:35:19 2020 +0200

    specify claim tokens
---
 core/api-common.rst   | 13 ++++++++++---
 core/api-merchant.rst | 19 ++++++++++++++++++-
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/core/api-common.rst b/core/api-common.rst
index 987ba66..ed799e9 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 2493608..25cee22 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

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.