[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] 02/02: document next-generation merchant API with CRUD APIs
|
From: |
gnunet |
|
Subject: |
[taler-docs] 02/02: document next-generation merchant API with CRUD APIs for accounts and OTP devices |
|
Date: |
Tue, 29 Aug 2023 22:54:39 +0200 |
This is an automated email from the git hooks/post-receive script.
grothoff pushed a commit to branch master
in repository docs.
commit 366c0d3c648e6cab4838c237258d32b6ae924a64
Author: Christian Grothoff <grothoff@gnunet.org>
AuthorDate: Tue Aug 29 22:54:31 2023 +0200
document next-generation merchant API with CRUD APIs for accounts and OTP
devices
---
core/api-merchant.rst | 476 +++++++++++++++++++++++++++++++++++++-------------
1 file 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;
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.