[taler-docs] branch master updated (afbf55d8 -> 366c0d3c)

[gnunet]

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

grothoff pushed a change to branch master
in repository docs.

    from afbf55d8 document environment variable substitution (#7013)
     new 0bc3a8a6 document v17 deposit struct
     new 366c0d3c document next-generation merchant API with CRUD APIs for 
accounts and OTP devices

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 core/api-common.rst   |   2 +-
 core/api-merchant.rst | 476 +++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 351 insertions(+), 127 deletions(-)

diff --git a/core/api-common.rst b/core/api-common.rst
index 90aee54e..ea30637f 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -1047,7 +1047,7 @@ within the
     struct TALER_AmountNBO deposit_fee;
     struct TALER_MerchantPublicKeyP merchant;
     struct TALER_OutputCommitmentHash h_outputs;
-    uint32_t subcontract_index_field;
+    struct GNUNET_HashCode wallet_data_hash;
   };
 
 .. _TALER_DepositConfirmationPS:
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 0940ef11..e3294263 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -477,6 +477,10 @@ again.
 
     interface PaidRefundStatusResponse {
 
+      // Text to be shown to the point-of-sale staff as a proof of
+      // payment (present only if re-usable OTP algorithm is used).
+      pos_confirmation?: string;
+
       // True if the order has been subjected to
       // refunds. False if it was simply paid.
       refunded: boolean;
@@ -916,13 +920,6 @@ Setting up instances
   .. ts:def:: InstanceConfigurationMessage
 
     interface InstanceConfigurationMessage {
-      // Bank accounts of the merchant.  A merchant may have
-      // multiple accounts, thus this is an array.  Note that by
-      // removing accounts from this list the respective account is set to
-      // inactive and thus unavailable for new contracts, but preserved
-      // in the database as existing offers and contracts may still refer
-      // to it.
-      accounts: MerchantBankAccount[];
 
       // Name of the merchant instance to create (will become $INSTANCE).
       // Must match the regex ``^[A-Za-z0-9][A-Za-z0-9_.@-]+$``.
@@ -1024,43 +1021,6 @@ Setting up instances
 
     }
 
-
-.. http:post:: [/instances/$INSTANCE]/private/account
-
-   Add an account to the list of bank accounts of the instance.  The POST
-   operation is authenticated by checking that an authorization is provided
-   that matches the credential required by the instance being modified.
-
-   **Request** the request must be of type `MerchantBankAccount`.
-
-  :http:statuscode:`204 No content`:
-    The backend has successfully created the instance.
-  :http:statuscode:`403 Forbidden`:
-    The provided credentials are invalid for this instance.
-  :http:statuscode:`404 Not found`:
-    This instance is unknown and thus an account cannot be added.
-  :http:statuscode:`409 Conflict`:
-    The given payto URI is already configured for this instance.
-
-
-.. http:delete:: [/instances/$INSTANCE]/private/account/$H_WIRE
-
-   Removes a bank account from the list of bank accounts of the instance.  The
-   ``$H_WIRE`` argument in the path must match the respective hash over the
-   wire details from the `MerchantAccount` returned from a GET operation on
-   the instance.  Technically, this operation does not delete the account, but
-   merely deactivates it.  The DELETE operation is authenticated by checking
-   that an authorization is provided that matches the credential required by
-   the instance being modified.
-
-  :http:statuscode:`204 No content`:
-    The backend has successfully deleted the account.
-  :http:statuscode:`403 Forbidden`:
-    The provided credentials are invalid for this instance.
-  :http:statuscode:`404 Not found`:
-    This instance or bank account are unknown and thus the account could not 
be deleted.
-
-
 .. http:patch:: /management/instances/$INSTANCE
 .. http:patch:: [/instances/$INSTANCE]/private
 
@@ -1085,11 +1045,6 @@ Setting up instances
   .. ts:def:: InstanceReconfigurationMessage
 
     interface InstanceReconfigurationMessage {
-      // Bank accounts of the merchant.  A merchant may have
-      // multiple accounts, thus this is an array.  Note that removing
-      // URIs from this list deactivates the specified accounts
-      // (they will no longer be used for future contracts).
-      accounts: MerchantBankAccount[];
 
       // Merchant name corresponding to this instance.
       name: string;
@@ -1208,9 +1163,6 @@ Inspecting instances
   .. ts:def:: QueryInstancesResponse
 
     interface QueryInstancesResponse {
-      // The URI where the wallet will send coins.  A merchant may have
-      // multiple accounts, thus this is an array.
-      accounts: MerchantAccount[];
 
       // Merchant name corresponding to this instance.
       name: string;
@@ -1260,61 +1212,6 @@ Inspecting instances
 
     }
 
-  .. ts:def:: MerchantAccount
-
-    interface MerchantAccount {
-
-      // payto:// URI of the account.
-      payto_uri: string;
-
-      // Hash over the wire details (including over the salt).
-      h_wire: HashCode;
-
-      // Salt used to compute h_wire.
-      salt: HashCode;
-
-      // URL from where the merchant can download information
-      // about incoming wire transfers to this account.
-      credit_facade_url?: string;
-
-      // Credentials to use when accessing the credit facade.
-      // Never returned on a GET (as this may be somewhat
-      // sensitive data). Can be set in POST
-      // or PATCH requests to update (or delete) credentials.
-      // To really delete credentials, set them to the type: "none".
-      credit_facade_credentials?: FacadeCredentials;
-
-      // true if this account is active,
-      // false if it is historic.
-      active: boolean;
-    }
-
-  .. ts:def:: FacadeCredentials
-
-    type FacadeCredentials =
-      | NoFacadeCredentials
-      | BasicAuthFacadeCredentials;
-
-  .. ts:def:: NoFacadeCredentials
-
-    interface NoFacadeCredentials {
-       type: "none";
-    };
-
-  .. ts:def:: BasicAuthFacadeCredentials
-
-    interface BasicAuthFacadeCredentials {
-       type: "basic";
-
-       // Username to use to authenticate
-       username: string;
-
-       // Password to use to authenticate
-       password: string;
-    };
-
-
-
 
 Deleting instances
 ------------------
@@ -1459,6 +1356,192 @@ KYC status checks
 
     }
 
+
+-------------
+Bank Accounts
+--------------
+
+One or more bank accounts must be associated with an instance
+so that the instance can receive payments.  Payments may be made
+into any of the active bank accounts of an instance.
+
+
+.. http:post:: [/instances/$INSTANCE]/private/accounts
+
+  This is used to add an account to an instance.
+
+  **Request:**
+
+  The request must be an `AccountAddDetails`.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    Adding the account was successful.
+  :http:statuscode:`404 Not found`:
+    The merchant instance is unknown or it is not in our data.
+  :http:statuscode:`409 Conflict`:
+    The provided information is inconsistent with the current state of the 
instance.
+    Usually this means we already have this account, but with conflicting 
credit facade information.
+    Inactive accounts can be reactivated using this method even if the
+    credit facade information differs from the previous state.
+
+  .. ts:def:: AccountAddDetails
+
+    interface AccountAddDetails {
+
+      // payto:// URI of the account.
+      payto_uri: string;
+
+      // Hash over the wire details (including over the salt).
+      h_wire: HashCode;
+
+      // Salt used to compute h_wire.
+      salt: HashCode;
+
+      // URL from where the merchant can download information
+      // about incoming wire transfers to this account.
+      credit_facade_url?: string;
+
+      // Credentials to use when accessing the credit facade.
+      // Never returned on a GET (as this may be somewhat
+      // sensitive data). Can be set in POST
+      // or PATCH requests to update (or delete) credentials.
+      // To really delete credentials, set them to the type: "none".
+      credit_facade_credentials?: FacadeCredentials;
+
+    }
+
+  .. ts:def:: FacadeCredentials
+
+    type FacadeCredentials =
+      | NoFacadeCredentials
+      | BasicAuthFacadeCredentials;
+
+  .. ts:def:: NoFacadeCredentials
+
+    interface NoFacadeCredentials {
+       type: "none";
+    };
+
+  .. ts:def:: BasicAuthFacadeCredentials
+
+    interface BasicAuthFacadeCredentials {
+       type: "basic";
+
+       // Username to use to authenticate
+       username: string;
+
+       // Password to use to authenticate
+       password: string;
+    };
+
+
+.. http:patch:: [/instances/$INSTANCE]/private/accounts/$H_WIRE
+
+  This is used to update a bank account.
+
+  **Request:**
+
+  The request must be a `AccountPatchDetails`.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The template has successfully modified.
+  :http:statuscode:`404 Not found`:
+    The template(ID) is unknown to the backend.
+
+  .. ts:def:: AccountPatchDetails
+
+   interface AccountPatchDetails {
+
+      // URL from where the merchant can download information
+      // about incoming wire transfers to this account.
+      credit_facade_url?: string;
+
+      // Credentials to use when accessing the credit facade.
+      // Never returned on a GET (as this may be somewhat
+      // sensitive data). Can be set in POST
+      // or PATCH requests to update (or delete) credentials.
+      // To really delete credentials, set them to the type: "none".
+      credit_facade_credentials?: FacadeCredentials;
+   }
+
+
+.. http:get:: [/instances/$INSTANCE]/private/accounts
+
+  This is used to return the list of all the bank accounts
+  of an instance.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+     The backend has successfully returned all the accounts. Returns a 
`AccountsSummaryResponse`.
+  :http:statuscode:`404 Not found`:
+     The backend has does not know about the instance.
+
+  .. ts:def:: AccountsSummaryResponse
+
+    interface AccountsSummaryResponse {
+
+      // List of accounts that are known for the instance.
+      accounts: BankAccountEntry[];
+    }
+
+  .. ts:def:: BankAccountEntry
+
+    interface BankAccountEntry {
+
+      // payto:// URI of the account.
+      payto_uri: string;
+
+      // Hash over the wire details (including over the salt).
+      h_wire: HashCode;
+
+      // Salt used to compute h_wire.
+      salt: HashCode;
+
+      // URL from where the merchant can download information
+      // about incoming wire transfers to this account.
+      credit_facade_url?: string;
+
+      // Credentials to use when accessing the credit facade.
+      // Never returned on a GET (as this may be somewhat
+      // sensitive data). Can be set in POST
+      // or PATCH requests to update (or delete) credentials.
+      // To really delete credentials, set them to the type: "none".
+      credit_facade_credentials?: FacadeCredentials;
+
+      // true if this account is active,
+      // false if it is historic.
+      active: boolean;
+    }
+
+.. http:get:: [/instances/$INSTANCE]/private/accounts/$H_WIRE
+
+  This is used to obtain detailed information about a specific bank account.
+
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The backend has successfully returned the detailed information about a 
specific bank account.
+    Returns a `BankAccountEntry`.
+  :http:statuscode:`404 Not found`:
+    The bank account or instance is unknown to the backend.
+
+
+.. http:delete:: [/instances/$INSTANCE]/private/accounts/$H_WIRE
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The backend has successfully deactivated the account.
+  :http:statuscode:`404 Not found`:
+    The backend does not know the instance or the account.
+
+
 --------------------
 Inventory management
 --------------------
@@ -1828,6 +1911,7 @@ Creating orders
     (2) The merchant instance is unknown (including possibly the instance
         being not configured for new orders).
     (3) The wire method specified is not supported by the backend.
+    (4) An OTP device ID was specified and is unknown.
 
     Details in the error code.
     NOTE: currently the client has no good way to find out which product
@@ -1879,6 +1963,9 @@ Creating orders
       // if the backend auto-generates one). Default is 'true'.
       create_token?: boolean;
 
+      // OTP device ID to associate with the order.
+      // This parameter is optional.
+      otp_id?: string;
     }
 
   .. ts:def:: Order
@@ -2915,11 +3002,157 @@ Checking tip status
       tip_amount: Amount;
     }
 
+-----------
+OTP Devices
+-----------
 
+OTP devices can be used to allow offline merchants
+to validate that a customer made a payment.
 
---------
-Template
---------
+
+.. http:post:: [/instances/$INSTANCE]/private/otp
+
+  This is used to associate an OTP device with an instance.
+
+  **Request:**
+
+  The request must be a `OtpDeviceAddDetails`.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The creation of the template is successful.
+  :http:statuscode:`404 Not found`:
+    The merchant instance is unknown or it is not in our data.
+
+  .. ts:def:: OtpDeviceAddDetails
+
+    interface OtpDeviceAddDetails {
+
+      // Device ID to use.
+      device_id: string;
+
+      // Human-readable description for the device.
+      device_description: string;
+
+      // A base64-encoded key
+      pos_key: string;
+
+      // Algorithm for computing the POS confirmation.
+      pos_algorithm: Integer;
+
+      // Counter for counter-based OTP devices.
+      pos_ctr?: Integer;
+    }
+
+
+.. http:patch:: [/instances/$INSTANCE]/private/otp/$DEVICE_ID
+
+  This is used to update an OTP device. It is useful when we need to change 
information in the OTP device or when we have mistake some information.
+
+  **Request:**
+
+  The request must be a `OtpDevicePatchDetails`.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The template has successfully modified.
+  :http:statuscode:`404 Not found`:
+    The template(ID) is unknown to the backend.
+  :http:statuscode:`409 Conflict`:
+    The provided information is inconsistent with the current state of the 
template. Changes made is the same with
+    another store.
+
+  .. ts:def:: OtpDevicePatchDetails
+
+   interface OtpDevicePatchDetails {
+
+     // Human-readable description for the device.
+     device_description: string;
+
+     // A base64-encoded key
+     pos_key: string;
+
+     // Algorithm for computing the POS confirmation.
+     pos_algorithm: Integer;
+
+     // Counter for counter-based OTP devices.
+     pos_ctr?: Integer;
+  }
+
+
+.. http:get:: [/instances/$INSTANCE]/private/otp
+
+  This is used to return the list of all the OTP devices.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+     The backend has successfully returned all the templates. Returns a 
`OtpDeviceSummaryResponse`.
+  :http:statuscode:`404 Not found`:
+     The backend has does not know about the instance.
+
+  .. ts:def:: OtpDeviceSummaryResponse
+
+    interface OtpDeviceSummaryResponse {
+
+      // List of devices that are present in our backend.
+      devices_list: OtpDeviceEntry[];
+    }
+
+  .. ts:def:: OtpDeviceEntry
+
+    interface OtpDeviceEntry {
+
+      // Device identifier.
+      device_id: string;
+
+      // Human-readable description for the device.
+      device_description: string;
+    }
+
+.. http:get:: [/instances/$INSTANCE]/private/otp/$DEVICE_ID
+
+  This is used to obtain detailed information about a specific OTP device.
+
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The backend has successfully returned the detailed information about a 
specific OTP device.
+    Returns a `OtpDeviceDetails`.
+  :http:statuscode:`404 Not found`:
+    The OTP device or instance is unknown to the backend.
+
+  .. ts:def:: OtpDeviceDetails
+
+    interface OtpDeviceDetails {
+
+      // Human-readable description for the device.
+      device_description: string;
+
+      // Algorithm for computing the POS confirmation.
+      pos_algorithm: Integer;
+
+      // Counter for counter-based OTP devices.
+      pos_ctr?: Integer;
+
+   }
+
+.. http:delete:: [/instances/$INSTANCE]/private/otp/$DEVICE_ID
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The backend has successfully deleted the OTP device.
+  :http:statuscode:`404 Not found`:
+    The backend does not know the instance or the OTP device.
+
+
+---------
+Templates
+---------
 
 The template is a backend feature that is used to allow wallets to create an
 order. This is useful in cases where a store does not have Internet
@@ -2996,12 +3229,9 @@ Adding templates
       // Human-readable description for the template.
       template_description: string;
 
-      // A base64-encoded key of the point-of-sale.
+      // OTP device ID.
       // This parameter is optional.
-      pos_key?: string;
-
-      // Algorithm for computing the POS confirmation, 0 for none.
-      pos_algorithm?: Integer;
+      otp_id?: string;
 
       // Additional information in a separate template.
       template_contract: TemplateContractDetails;
@@ -3060,12 +3290,9 @@ Editing templates
       // Human-readable description for the template.
       template_description: string;
 
-      // A base64-encoded key of the point-of-sale.
+      // OTP device ID.
       // This parameter is optional.
-      pos_key?: string;
-
-      // Algorithm for computing the POS confirmation, 0 for none.
-      pos_algorithm?: Integer;
+      otp_id?: string;
 
       // Additional information in a separate template.
       template_contract: TemplateContractDetails;
@@ -3122,7 +3349,7 @@ Inspecting template
     The backend has successfully returned the detailed information about a 
specific template.
     Returns a `TemplateDetails`.
   :http:statuscode:`404 Not found`:
-    The template(ID) is unknown to the backend.
+    The instance or template(ID) is unknown to the backend.
 
 
   .. ts:def:: TemplateDetails
@@ -3132,12 +3359,9 @@ Inspecting template
       // Human-readable description for the template.
       template_description: string;
 
-      // A base64-encoded key of the point-of-sale.
+      // OTP device ID.
       // This parameter is optional.
-      pos_key?: string;
-
-      // Algorithm for computing the POS confirmation, 0 for none.
-      pos_algorithm?: Integer;
+      otp_id?: string;
 
       // Additional information in a separate template.
       template_contract: TemplateContractDetails;

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