summaryrefslogtreecommitdiff
path: root/core
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-07-27 10:35:19 +0200
committerChristian Grothoff <christian@grothoff.org>2020-07-27 10:35:19 +0200
commite15e209e76e7970c73b4e359dba2196ffc9b9c6d (patch)
tree25d6173930aa317096faa6707130b24eb64ab0ec /core
parent258de337784e561526e7cb307591ad21e34a416c (diff)
downloaddocs-e15e209e76e7970c73b4e359dba2196ffc9b9c6d.tar.gz
docs-e15e209e76e7970c73b4e359dba2196ffc9b9c6d.tar.bz2
docs-e15e209e76e7970c73b4e359dba2196ffc9b9c6d.zip
specify claim tokens
Diffstat (limited to 'core')
-rw-r--r--core/api-common.rst13
-rw-r--r--core/api-merchant.rst19
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