diff options
Diffstat (limited to 'core/api-merchant.rst')
| -rw-r--r-- | core/api-merchant.rst | 525 |
1 files changed, 508 insertions, 17 deletions
diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 519a4324..f686b302 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -16,6 +16,7 @@ @author Marcello Stanisci @author Florian Dold @author Christian Grothoff + @author Priscilla Huang .. _merchant-api: @@ -25,6 +26,7 @@ Merchant Backend API .. contents:: Table of Contents + ----------------------- Base URLs and Instances ----------------------- @@ -38,7 +40,7 @@ instance is used when no explicit instance is specified. Despite its name, this instance must be created after the installation. In case *no* default instance is found - or its credentials got lost -, the administrator can use the default instance's rights by resorting on the ``--auth`` command line option, -or by restarting the service by providing a environment variable called +or by restarting the service by providing an environment variable called ``TALER_MERCHANT_TOKEN``. Each instance (default and others) has a base URL. The resources under @@ -118,7 +120,7 @@ such as the implemented version of the protocol and the currency used. **Response:** :http:statuscode:`200 OK`: - The exchange accepted all of the coins. The body is a `VersionResponse`. + The body is a `VersionResponse`. .. ts:def:: VersionResponse @@ -245,18 +247,22 @@ Making the payment The merchant backend could not find the order or the instance and thus cannot process the payment. :http:statuscode:`406 Not acceptable`: The payment is insufficient (sum is below the required total amount). + TODO: Should probably change to a different status code in the future as 406 is technically wrong. :http:statuscode:`408 Request timeout`: The backend took too long to process the request. Likely the merchant's connection to the exchange timed out. Try again. :http:statuscode:`409 Conflict`: - The exchange rejected the payment because a coin was already spent. - The response will include the ``coin_pub`` for which the payment failed, - in addition to the response from the exchange to the ``/deposit`` request. + The exchange rejected the payment because a coin was already spent, or + the merchant rejected the payment because the order was already fully paid + (and then return signatures with refunds). If a coin was already spent, + the response will include the ``exchange_url`` for which the payment failed, + in addition to the response from the exchange to the ``/batch-deposit`` request. :http:statuscode:`410 Gone`: The offer has expired and is no longer available. :http:statuscode:`412 Precondition failed`: The given exchange is not acceptable for this merchant, as it is not in the list of accepted exchanges and not audited by an approved auditor. + TODO: Status code may be changed to 409 in the future as 412 is technically wrong. :http:statuscode:`502 Bad gateway`: The merchant's interaction with the exchange failed in some way. The client might want to try again later. @@ -381,6 +387,9 @@ Querying payment status // Amount that was refunded in total. refund_amount: Amount; + + // Amount that already taken by the wallet. + refund_taken: Amount; } .. ts:def:: StatusGotoResponse @@ -848,7 +857,7 @@ Instance management ------------------- Instances allow one merchant backend to be shared by multiple merchants. -Every backend must have at least one instance, typcially the "default" +Every backend must have at least one instance, typically the "default" instance setup before it can be used to manage inventory or process payments. @@ -894,6 +903,15 @@ Setting up instances // Merchant name corresponding to this instance. name: string; + // Merchant email for customer contact. + email?: string; + + // Merchant public website. + website?: string; + + // Merchant logo. + logo?: ImageDataUrl; + // Authentication settings for this instance auth: InstanceAuthConfigurationMessage; @@ -998,6 +1016,15 @@ Setting up instances // Merchant name corresponding to this instance. name: string; + // Merchant email for customer contact. + email?: string; + + // Merchant public website. + website?: string; + + // Merchant logo. + logo?: ImageDataUrl; + // The merchant's physical address (to be put into contracts). address: Location; @@ -1063,6 +1090,12 @@ Inspecting instances // Merchant name corresponding to this instance. name: string; + // Merchant public website. + website?: string; + + // Merchant logo. + logo?: ImageDataUrl; + // Merchant instance this response is about ($INSTANCE). id: string; @@ -1103,6 +1136,15 @@ Inspecting instances // Merchant name corresponding to this instance. name: string; + // Merchant email for customer contact. + email?: string; + + // Merchant public website. + website?: string; + + // Merchant logo. + logo?: ImageDataUrl; + // Public key of the merchant/instance, in Crockford Base32 encoding. merchant_pub: EddsaPublicKey; @@ -1274,14 +1316,14 @@ KYC status checks .. ts:def:: ExchangeKycTimeout - interface ExchangeKycTimeout { + interface ExchangeKycTimeout { - // Base URL of the exchange this is about. - exchange_url: string; + // Base URL of the exchange this is about. + exchange_url: string; - // Numeric `error code <error-codes>` indicating errors the exchange - // returned, or TALER_EC_INVALID for none. - exchange_code: number; + // Numeric `error code <error-codes>` indicating errors the exchange + // returned, or TALER_EC_INVALID for none. + exchange_code: number; // HTTP status code returned by the exchange when we asked for // information about the KYC status. @@ -1363,6 +1405,9 @@ Adding products to the inventory // Identifies when we expect the next restocking to happen. next_restock?: Timestamp; + // Minimum age buyer must have (in years). Default is 0. + minimum_age?: Integer; + } @@ -1435,6 +1480,9 @@ Adding products to the inventory // Identifies when we expect the next restocking to happen. next_restock?: Timestamp; + // Minimum age buyer must have (in years). Default is 0. + minimum_age?: Integer; + } Inspecting inventory @@ -1526,6 +1574,9 @@ Inspecting inventory // Identifies when we expect the next restocking to happen. next_restock?: Timestamp; + // Minimum age buyer must have (in years). + minimum_age?: Integer; + } @@ -1799,8 +1850,8 @@ Inspecting orders :query paid: *Optional*. If set to yes, only return paid orders, if no only unpaid orders. Do not give (or use "all") to see all orders regardless of payment status. :query refunded: *Optional*. If set to yes, only return refunded orders, if no only unrefunded orders. Do not give (or use "all") to see all orders regardless of refund status. :query wired: *Optional*. If set to yes, only return wired orders, if no only orders with missing wire transfers. Do not give (or use "all") to see all orders regardless of wire transfer status. - :query delta: *Optional*. takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` and ``date_ms`` are returned. Defaults to ``-20`` to return the last 20 entries (before ``start`` and/or ``date_ms``). - :query date_ms: *Optional.* Non-negative date in milliseconds after the UNIX Epoc, see ``delta`` for its interpretation. If not specified, we default to the oldest or most recent entry, depending on ``delta``. + :query delta: *Optional*. takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` and ``date_s`` are returned. Defaults to ``-20`` to return the last 20 entries (before ``start`` and/or ``date_s``). + :query date_s: *Optional.* Non-negative date in seconds after the UNIX Epoc, see ``delta`` for its interpretation. If not specified, we default to the oldest or most recent entry, depending on ``delta``. :query start: *Optional*. Row number threshold, see ``delta`` for its interpretation. Defaults to ``INT64_MAX``, namely the biggest row id possible in the database. :query timeout_ms: *Optional*. Timeout in milliseconds to wait for additional orders if the answer would otherwise be negative (long polling). Only useful if delta is positive. Note that the merchant MAY still return a response that contains fewer than ``delta`` orders. @@ -1985,6 +2036,9 @@ Inspecting orders // Reason given for the refund. reason: string; + // Set to true if a refund is still available for the wallet for this payment. + pending: boolean; + // When was the refund approved. timestamp: Timestamp; @@ -2492,7 +2546,7 @@ once we got a reply from the exchange. .. http:delete:: [/instances/$INSTANCE]/private/transfers/$TID - Here, the TID ist the 'transfer_serial_id' of the transfer + Here, the TID is the 'transfer_serial_id' of the transfer to delete. **Response:** @@ -2901,7 +2955,7 @@ Checking tip status .. ts:def:: Tip - interface Tip { + interface Tip { // ID of the tip in the backend database. row_id: number; @@ -2915,6 +2969,434 @@ Checking tip status +-------- +Template +-------- + +The template is a backend feature that is used to create an order. We use the template to have some static information that cannot be changed by the customer. +The template is private and allows us to be flexible. The private template allows for greater security and allows us to have a minimum information we need for each store. + + + +Adding templates +---------------- + +.. http:post:: [/instances/$INSTANCE]/private/templates + + This is used to create a template. + + **Request:** + + The request must be a `TemplateAddDetails`. + + + **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:: TemplateAddDetails + + interface TemplateAddDetails { + + // Template ID to use. + template_id: string; + + // Human-readable description for the template. + template_description: string; + + // A base64-encoded image selected by the merchant. + // This parameter is optional. + // We are not sure about it. + image?: ImageDataUrl; + + // Additional information in a separate template. + template_contract: TemplateContractDetails; + } + + + .. ts:def:: TemplateContractDetails + + interface TemplateContractDetails { + + // Human-readable summary for the template. + summary?: string; + + // The price is imposed by the merchant and cannot be changed by the customer. + // This parameter is optional. + amount?: Amount; + + // Minimum age buyer must have (in years). Default is 0. + minimum_age: Integer; + + // The time the customer need to pay before his order will be deleted. + // It is deleted if the customer did not pay and if the duration is over. + pay_duration: RelativeTime; + + } + + + +Editing templates +----------------- + + +.. http:patch:: [/instances/$INSTANCE]/private/templates/$TEMPLATE_ID + + This is used to update a template. It is useful when we need to change information in the template or when we have mistake some information. + + **Request:** + + The request must be a `TemplatePatchDetails`. + + **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:: TemplatePatchDetails + + interface TemplatePatchDetails { + + // Human-readable description for the template. + template_description: string; + + // A base64-encoded image selected by the merchant. + // This parameter is optional. + // We are not sure about it. + image?: ImageDataUrl; + + // Additional information in a separate template. + template_contract: TemplateContractDetails; + + } + + + +Inspecting template +------------------- + +.. http:get:: [/instances/$INSTANCE]/private/templates + + This is used to return the list of all the templates. + + + **Response:** + + :http:statuscode:`200 OK`: + The backend has successfully returned all the templates. Returns a `TemplateSummaryResponse`. + :http:statuscode:`404 Not found`: + The backend has does not know about the instance. + + .. ts:def:: TemplateSummaryResponse + + interface TemplateSummaryResponse { + + // List of templates that are present in our backend. + templates_list: TemplateEntry[]; + } + + The `TemplatesEntry` object describes a template. It has the following structure: + + .. ts:def:: TemplateEntry + + interface TemplateEntry { + + // Template identifier, as found in the template. + template_id: string; + + // Human-readable description for the template. + template_description: string; + + } + +.. http:get:: [/instances/$INSTANCE]/private/templates/$TEMPLATE_ID + + This is used to obtain detailed information about a specific template. + + + **Response:** + + :http:statuscode:`200 OK`: + 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. + + + .. ts:def:: TemplateDetails + + interface TemplateDetails { + + // Human-readable description for the template. + template_description: string; + + // A base64-encoded image selected by the merchant. + // This parameter is optional. + // We are not sure about it. + image?: ImageDataUrl; + + // Additional information in a separate template. + template_contract: TemplateContractDetails; + } + + + +Removing template +----------------- + +.. http:delete:: [/instances/$INSTANCE]/private/templates/$TEMPLATE_ID + + This is used to delete information about a template. If we no longer use it. + + **Response:** + + :http:statuscode:`204 No content`: + The backend has successfully deleted the template. + :http:statuscode:`404 Not found`: + The backend does not know the instance or the template. + + + +Using template +---------------- + +.. http:post:: [/instances/$INSTANCES]/templates/$TEMPLATE_ID + + This using template can be modified by everyone and will be used to create order. + + + **Request:** + + The request must be a `UsingTemplateDetails` and we accept JSON application and URL encoded. + + + **Response:** + + :http:statuscode:`200 OK`: + The using template is successful. Returns a `UsingTemplateResponse`. + :http:statuscode:`302 Found`: + The client should go to the indicated location. Only returned if the content type was HTML. The target site may allow the client to pay his order. + :http:statuscode:`404 Not found`: + The merchant instance is unknown or the template is unknown. + + + .. ts:def:: UsingTemplateDetails + + interface UsingTemplateDetails { + + // Summary of the template + summary?: string; + + // The amount entered by the customer. + amount?: Amount; + } + + .. ts:def:: UsingTemplateResponse + + interface UsingTemplateResponse { + + // After enter the request. The user will be pay with a taler URL. + taler_url: string; + } + + +-------- +Webhooks +-------- + +The webhook is a backend feature that is used to send a confirmation to the merchant. It can be send with a SMS, email or with another method. It will confirm that the +customer paid the merchant. It will show the date and the price the customer paid. + + + +Adding webhooks +--------------- + +.. http:post:: [/instances/$INSTANCES]/private/webhooks + + This is used to create a webhook. + + **Request:** + + The request must be a `WebhookAddDetails`. + + **Response:** + + :http:statuscode:`204 No content`: + The creation of the webhook is successsful. + + :http:statuscode:`404 Not found`: + The merchant instance is unknowm or it not in our data. + + .. ts:def:: WebhookAddDetails + + interface WebhookAddDetails { + + // Webhook ID to use. + webhook_id: string; + + // The event of the webhook: why the webhook is used. + event_type: string; + + // URL of the webhook where the customer will be redirected. + url: string; + + // Method used by the webhook + http_method: string; + + // Header template of the webhook + header_template?: string; + + // Body template by the webhook + body_template?: string; + + } + + +Editing webhooks +---------------- + +.. http:patch:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID + + This is used to update a webhook. + + **Request:** + + The request must be a `WebhookPatchDetails`. + + **Response:** + + :http:statuscode:`204 No content`: + The webhook has successfully modified. + :http:statuscode:`404 Not found`: + The webhook(ID) is unknown to the backend. + :http:statuscode:`409 Conflict`: + The provided information is inconsistent with the current state of the webhook. Changes made is the same with another store. + + .. ts:def:: WebhookPatchDetails + + interface WebhookPatchDetails { + + // The event of the webhook: why the webhook is used. + event_type: string; + + // URL of the webhook where the customer will be redirected. + url: string; + + // Method used by the webhook + http_method: string; + + // Header template of the webhook + header_template?: string; + + // Body template by the webhook + body_template?: string; + + } + + + +Inspecting webhook +------------------ + +.. http:get:: [/instances/$INSTANCES]/private/webhooks + + This is used to return the list of all the webhooks. + + **Response:** + + :http:statuscode:`200 OK`: + The backend has successfully returned all the webhooks. Returns a `WebhookSummaryResponse`. + + :http:statuscode:`404 Not found`: + The backend has does not know about the instance. + + .. ts:def:: WebhookSummaryResponse + + interface WebhookSummaryResponse { + + // List of webhooks that are present in our backend. + webhooks_list: WebhookEntry[]; + + } + + The WebhookEntry object describes a webhook. It has the following structure: + + .. ts:def:: WebhookEntry + + interface WebhookEntry { + + // Webhook identifier, as found in the webhook. + webhook_id: string; + + // The event of the webhook: why the webhook is used. + event_type: string; + + } + + +.. http:get:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID + + This is used to obtain detailed information about apecific template. + + **Response:** + + :http:statuscode:`200 OK`: + The backend has successfully returned the detailed information about a specific webhook. Returns a `WebhookDetails`. + + :http:statuscode:`404 Not found`: + The webhook(ID) is unknown to the backend. + + + .. ts:def:: WebhookDetails + + interface WebhookDetails { + + // The event of the webhook: why the webhook is used. + event_type: string; + + // URL of the webhook where the customer will be redirected. + url: string; + + // Method used by the webhook + http_method: string; + + // Header template of the webhook + header_template?: string; + + // Body template by the webhook + body_template?: string; + + } + + +Removing webhook +----------------- + +.. http:delete:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID + + This is used to delete information about a webhook. + + **Response:** + + :http:statuscode:`204 No content`: + The backend has successfully deleted the webhook. + + :http:statuscode:`404 Not found`: + The webhook(ID) or the instance is unknown to the backend. + + + ------------------ The Contract Terms ------------------ @@ -3069,7 +3551,7 @@ The contract terms must have the following structure: extra?: any; } -The wallet must select a exchange that either the merchant accepts directly by +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. @@ -3124,6 +3606,15 @@ It has the following structure: name: string; // Label for a location with the business address of the merchant. + email?: string; + + // Label for a location with the business address of the merchant. + website?: string; + + // An optional base64-encoded product image. + logo?: ImageDataUrl; + + // Label for a location with the business address of the merchant. address?: Location; // Label for a location that denotes the jurisdiction for disputes. |