document next-generation merchant API with CRUD APIs for accounts and OTP devices

1 files changed, 350 insertions, 126 deletions

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;