[taler-docs] branch master updated: merchant api: draft of choices in orders creation

[gnunet]

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

christian-blaettler pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 706fb03e merchant api: draft of choices in orders creation
706fb03e is described below

commit 706fb03eb043b3f2dfb0897066e35fa759461d69
Author: Christian Blättler <blatc2@bfh.ch>
AuthorDate: Tue Mar 26 22:12:48 2024 +0100

    merchant api: draft of choices in orders creation
---
 core/api-merchant.rst | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index ac8e612e..28ca8dab 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -3580,6 +3580,10 @@ The contract terms must have the following structure:
     // encoded in it (such as a short product identifier and timestamp).
     order_id: string;
 
+    // List of contract choices that the customer can select from.
+    // @since protocol **vSUBSCRIBE**
+    choices: ContractChoice[];
+
     // Total price for the transaction.
     // The exchange will subtract deposit fees from that amount
     // before transferring it to the merchant.
@@ -3714,6 +3718,89 @@ The wallet must select an exchange that either the 
merchant accepts directly by
 listing it in the exchanges array, or for which the merchant accepts an auditor
 that audits that exchange by listing it in the auditors array.
 
+The `ContractChoice` object describes a possible choice within a contract. The
+choice is done by the customer and consists of in- and outputs. In the example
+of buying an article, the merchant could present the customer with the choice
+to use a valid subscription token or pay using a gift voucher. Available since
+protocol **vSUBSCRIBE**.
+
+.. ts:def:: ContractChoice
+
+  interface ContractChoice {
+    // Inputs that must be provided by the customer, if this choice is 
selected.
+    inputs: ContractInput[];
+
+    // Outputs provided by the merchant, if this choice is selected.
+    outputs: ContractOutput[];
+  }
+
+.. ts:def:: ContractInput
+
+  // For now, only token inputs are supported.
+  type ContractInput = ContractInputToken;
+
+.. ts:def:: ContractInputToken
+
+  interface ContractInputToken {
+
+    // Token input.
+    type: "token";
+
+    // How many units of the input are required. Defaults to 1 if not 
specified.
+    // Input with number == 0 are ignored by the merchant backend.
+    number?: Integer;
+
+    // Token family slug as configured in the merchant backend. Slug is unique
+    // across all configured tokens of a merchant.
+    token_family_slug: string;
+
+    // TODO: Is this only relevant for subscriptions or also for discounts?
+    // Start of the validity period of the subscription token. Based on this,
+    // the merchant will select the relevant signing key. Is null for 
discounts.
+    valid_after?: Timestamp;
+
+  }
+
+.. ts:def:: ContractOutput
+
+  type ContractOutput = ContractOutputToken | ContractOutputTaxReceipt;
+
+.. ts:def:: ContractOutputToken
+
+  interface ContractOutputToken {
+
+    // Token output.
+    type: "token";
+
+    // How many units of the output are yielded. Defaults to 1 if not 
specified.
+    // Output with number == 0 are ignored by the merchant backend.
+    number?: Integer;
+
+    // Token family slug as configured in the merchant backend. Slug is unique
+    // across all configured tokens of a merchant.
+    // TODO: Should we rename this to token_family_slug?
+    authority_label: string;
+
+    // TODO: Is this only relevant for subscriptions or also for discounts?
+    // Start of the validity period of the subscription token. Based on this,
+    // the merchant will select the relevant signing key. Is null for 
discounts.
+    valid_after?: Timestamp;
+
+  }
+
+.. ts:def:: ContractOutputTaxReceipt
+
+  interface ContractOutputTaxReceipt {
+
+    // Tax receipt output.
+    type: "tax-receipt";
+
+    // Base URL of the donation authority that will
+    // issue the tax receipt.
+    donau_url: string;
+
+  }
+
 The `Product` object describes the product being purchased from the merchant.
 It has the following structure:
 

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