summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2018-02-01 18:41:27 +0100
committerFlorian Dold <florian.dold@gmail.com>2018-02-01 18:41:27 +0100
commit78c52ddc698dca2c8f42308ea2cb7970ed49956e (patch)
treea27b00f2f00cf018094f31328271668c1c450744
parentce279a98dca012cba10f258625c44497a628872c (diff)
downloaddocs-78c52ddc698dca2c8f42308ea2cb7970ed49956e.tar.gz
docs-78c52ddc698dca2c8f42308ea2cb7970ed49956e.tar.bz2
docs-78c52ddc698dca2c8f42308ea2cb7970ed49956e.zip
doc fixes
-rw-r--r--api-common.rst24
-rw-r--r--api-exchange.rst4
-rw-r--r--api-merchant.rst97
-rw-r--r--exts/tsref.py4
4 files changed, 70 insertions, 59 deletions
diff --git a/api-common.rst b/api-common.rst
index 1526d7ef..ff0e0890 100644
--- a/api-common.rst
+++ b/api-common.rst
@@ -225,13 +225,27 @@ Signatures
Amounts
^^^^^^^
-Amounts of currency are expressed as a JSON object with the following fields:
-
.. _`tsref-type-Amount`:
+Amounts of currency are serialized as a string of the format `<Currency>:<DecimalAmount>`.
+Taler treats monetary amounts as fixed-precision numbers. Unlike floating point numbers,
+this allows accurate representation of monetary amounts.
+
+The following constrains apply for a valid amount:
+
+1. The `<Currency>` part must be at most 12 characters long and may not contain a colon (`:`).
+2. The integer part of `<DecimalAmount>` may be at most 2^52
+3. the fractional part of `<DecimalAmount>` may contain at most 8 decimal digits.
+
+Internally, amounts are parsed into the following object:
+
+.. note::
+
+ "EUR:1.50" and "EUR:10" are is a valid amounts. These are all invalid amounts: "A:B:1.5", "EUR:4503599627370501.0", "EUR:1.", "EUR:.1"
+
.. code-block:: tsref
- interface Amount {
+ interface ParsedAmount {
// name of the currency using either a three-character ISO 4217 currency
// code, or a regional currency identifier starting with a "*" followed by
// at most 10 characters. ISO 4217 exponents in the name are not supported,
@@ -438,6 +452,10 @@ Any piece of signed data, complies to the abstract data structure given below.
/*From gnunet_crypto_lib.h*/
struct GNUNET_CRYPTO_EccSignaturePurpose {
/**
+
+ The following constrains apply for a valid amount:
+
+ * asd
* This field is used to express the context in
* which the signature is made, ensuring that a
* signature cannot be lifted from one part of the protocol
diff --git a/api-exchange.rst b/api-exchange.rst
index 2d95c67f..0c117775 100644
--- a/api-exchange.rst
+++ b/api-exchange.rst
@@ -1276,10 +1276,6 @@ typically also view the balance.)
Refunds
-------
- .. note::
-
- Refunds are currently not implemented (#3641), this documentation is thus a bit preliminary and may still change.
-
.. _refund:
.. http:POST:: /refund
diff --git a/api-merchant.rst b/api-merchant.rst
index 5b03900b..7695417d 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -23,41 +23,48 @@
Merchant Backend API
====================
-Please refer to the `glossary <https://docs.taler.net/glossary.html>`_ for terms
-like `order`, `proposal`, `contract`, and others.
-
-
------------------
-Receiving payments
+Receiving Payments
------------------
+.. _post-order:
+
.. http:post:: /order
Create a new order that a customer can pay for.
This request is not idempotent unless an `order_id` is explicitly specified.
- **Request:**
+ .. note::
- The request must be an `OrderRequest`_. Note that it can overwrite all fields of the `ContractTerms`_.
+ This endpoint does not return a URL to redirect your user to confirm the payment.
+ In order to get this URL use :http:get:`/check-payment`. The API is structured this way
+ since the payment redirect URL is not unique for every order, there might be varying parameters
+ such as the session id.
+ **Request:**
+
+ The request must be a `PostOrderRequest`_.
**Response**
-
+
:status 200 OK:
The backend has successfully created the proposal. The response is a
- `OrderResponse`_. Use `/check-pay` to get a URL that allows the customer
- to confirm the payment in their browser/wallet.
- :status 403 Forbidden:
- The frontend used the same order ID with different content in the order.
+ `PostOrderResponse`_.
- .. _OrderRequest:
+ .. _PostOrderRequest:
.. code-block:: tsref
- // Union of both structures
- type OrderRequest = ContractTerms | MinimalOrderRequest;
+ interface PostOrderRequest {
+ // The order must at least contain the minimal
+ // order detail, but can override all
+ order: MinimalOrderDetail | ContractTerms;
+ }
+
+ The following fields of the `ContractTerms`_
- .. _MinimalOrderRequest:
+ .. _MinimalOrderDetail:
+ .. _tsref-type-MinimalOrderDetail:
.. code-block:: tsref
interface MinimalOrderRequest {
@@ -76,10 +83,10 @@ Receiving payments
instance?: string;
}
- .. _OrderResponse:
+ .. _PostOrderResponse:
.. code-block:: tsref
- interface OrderResponse {
+ interface PostOrderResponse {
// Order ID of the response that was just created
order_id: string;
}
@@ -87,7 +94,8 @@ Receiving payments
.. http:get:: /check-payment
- Check the status of a payment.
+ Check the payment status of an order. If the order exists but is not payed yet,
+ a redirect URL. When the user goes to this URL, they will be prompted for payment.
**Request:**
@@ -109,6 +117,7 @@ Receiving payments
type CheckPaymentResponse = CheckPaymentPaidResponse | CheckPaymentUnpaidResponse
.. _CheckPaymentPaidResponse:
+ .. _tsref-type-CheckPaymentPaidResponse:
.. code-block:: tsref
interface CheckPaymentPaidResponse {
@@ -125,6 +134,7 @@ Receiving payments
}
.. _CheckPaymentUnpaidResponse:
+ .. _tsref-type-CheckPaymentUnpaidResponse:
.. code-block:: tsref
interface CheckPaymentUnpaidResponse {
@@ -138,7 +148,7 @@ Receiving payments
--------------
-Giving refunds
+Giving Refunds
--------------
@@ -172,7 +182,7 @@ Giving refunds
reason: string;
// Merchant instance issuing the request
- instance: string;
+ instance?: string;
}
.. _MerchantRefundResponse:
@@ -196,6 +206,7 @@ Giving refunds
}
.. _MerchantRefundPermission:
+ .. _tsref-type-MerchantRefundPermissoin:
.. code-block:: tsref
interface MerchantRefundPermission {
@@ -216,9 +227,9 @@ Giving refunds
}
-------------------------
-Giving tips to customers
-------------------------
+--------------------
+Giving Customer Tips
+--------------------
.. http:post:: /tip-authorize
@@ -249,15 +260,11 @@ Giving tips to customers
amount: Amount;
// Merchant instance issuing the request
- instance: string;
+ instance?: string;
// Justification for giving the tip
justification: string;
- // URL that the wallet should pick up the tip from,
- // will be included in the tip_token.
- pickup_url: string;
-
// URL that the user should be directed to after tipping,
// will be included in the tip_token.
next_url: string;
@@ -272,15 +279,6 @@ Giving tips to customers
// a tip.
tip_token: string;
- // Identifier for the tip authorization
- tip_id: HashCode;
-
- // Expiration time for obtaining the tip
- expiration: Timestamp;
-
- // URL of the exchange from where the tip can be withdrawn
- exchange_uri: String;
-
// URL that will directly trigger procesing
// the tip when the browser is redirected to it
tip_redirect_url: string;
@@ -326,7 +324,7 @@ Giving tips to customers
------------------------
-Tracking wire transfers
+Tracking Wire Transfers
------------------------
.. http:get:: /track/transfer
@@ -455,15 +453,13 @@ Tracking wire transfers
**Request:**
:query id: ID of the transaction we want to trace (an integer)
- :query instance: identificative token for the merchant instance which is to be tracked (optional). See `<https://docs.taler.net/operate-merchant.html#instances-lab>`_. This information is needed because the request has to be signed by the merchant, thus we need to pick the instance's private key.
+ :query instance: merchant instance
**Response:**
:status 200 OK:
The deposit has been executed by the exchange and we have a wire transfer identifier.
- The response body is a JSON array of `TransactionWireTransfer`_ objects.
-
-
+ The response body is a JSON array of `TransactionWireTransfer`_ objects.
:status 202 Accepted:
The deposit request has been accepted for processing, but was not yet
executed. Hence the exchange does not yet have a wire transfer identifier.
@@ -471,11 +467,12 @@ Tracking wire transfers
The response body is a :ref:`TrackTransactionAcceptedResponse <TrackTransactionAcceptedResponse>`. Note that
the similarity to the response given by the exchange for a /track/order
is completely intended.
-
:status 404 Not Found: The transaction is unknown to the backend.
-
:status 424 Failed Dependency:
- The exchange previously claimed that a deposit was not included in a wire transfer, and now claims that it is. This means that the exchange is dishonest. The response contains the cryptographic proof that the exchange is misbehaving in the form of a `TransactionConflictProof`_.
+ The exchange previously claimed that a deposit was not included in a wire
+ transfer, and now claims that it is. This means that the exchange is
+ dishonest. The response contains the cryptographic proof that the exchange
+ is misbehaving in the form of a `TransactionConflictProof`_.
**Details:**
@@ -589,7 +586,7 @@ Transaction history
.. _proposal:
------------------
-The contract terms
+The Contract Terms
------------------
The `contract terms` must have the following structure:
@@ -703,13 +700,13 @@ The `contract terms` must have the following structure:
description: string;
// The quantity of the product to deliver to the customer (optional, if applicable)
- quantity?: number;
+ quantity?: string;
// The price of the product; this is the total price for the amount specified by `quantity`
price: Amount;
- // merchant's 53-bit internal identification number for the product (optional)
- product_id?: number;
+ // merchant-internal identifier for the product
+ product_id?: string;
// a list of objects indicating a `taxname` and its amount. Again, italics denotes the object field's name.
taxes?: any[];
diff --git a/exts/tsref.py b/exts/tsref.py
index 8187f67f..ae108324 100644
--- a/exts/tsref.py
+++ b/exts/tsref.py
@@ -223,10 +223,10 @@ def remember_targets(app, doctree):
def setup(app):
from sphinx.highlighting import lexers
- from pygments.lexers import TypeScriptLexer
from pygments.token import Name
from pygments.filters import NameHighlightFilter
- lexer = TypeScriptLexer()
+ from tslex import BetterTypeScriptLexer
+ lexer = BetterTypeScriptLexer()
lexer.add_filter(LinkFilter(app))
app.add_lexer('tsref', lexer)
app.add_builder(MyHtmlBuilder)