summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarcello Stanisci <marcello.stanisci@inria.fr>2016-10-21 16:15:45 +0200
committerMarcello Stanisci <marcello.stanisci@inria.fr>2016-10-21 16:15:45 +0200
commit283b5901e54fb6051876639d7f7819715e100d38 (patch)
tree136296f40a3f9563bb57fcb7a4a4872dc79b51d5
parentf46102c0bddc001769817046ae50e6e65b4769d1 (diff)
parent835509f59bd11234b0181693396ad40b5ff8e5fc (diff)
downloaddocs-283b5901e54fb6051876639d7f7819715e100d38.tar.gz
docs-283b5901e54fb6051876639d7f7819715e100d38.tar.bz2
docs-283b5901e54fb6051876639d7f7819715e100d38.zip
Merge branch 'master' of ssh://taler.net/api
-rw-r--r--api-common.rst4
-rw-r--r--api-exchange.rst8
-rw-r--r--api-merchant.rst84
3 files changed, 85 insertions, 11 deletions
diff --git a/api-common.rst b/api-common.rst
index 3bbc8722..d44e55ec 100644
--- a/api-common.rst
+++ b/api-common.rst
@@ -70,8 +70,8 @@ handle the error as if an internal error (500) had been returned.
interface ErrorDetail {
- // Numeric error code. See "taler_error_codes.h".
- error_code: number;
+ // Numeric error code unique to the condition. See "taler_error_codes.h".
+ code: number;
// Human-readable description of the error, i.e. "missing parameter", "commitment violation", ...
// The other arguments are specific to the error value reported here.
diff --git a/api-exchange.rst b/api-exchange.rst
index e1439936..d53056fb 100644
--- a/api-exchange.rst
+++ b/api-exchange.rst
@@ -360,7 +360,7 @@ exchange.
// `base32`_ encoding of `TALER_WithdrawRequestPS`_ with purpose TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW. This field appears only if `type` is "WITHDRAW".
details?: string;
- // Signature over the transaction `details`.
+ // Signature over the transaction `details` (FIXME: Which transaction, which details?).
signature?: EddsaSignature;
}
@@ -392,7 +392,7 @@ exchange.
not yet have completed and might be known to the exchange in the near future.
In this case, the wallet should repeat the exact same request later again
using exactly the same blinded coin.
- :status 402 Payment Required:
+ :status 403 Forbidden:
The balance of the reserve is not sufficient to withdraw a coin of the indicated denomination.
The response is `WithdrawError`_ object.
@@ -475,7 +475,7 @@ denomination.
The operation succeeded, the exchange confirms that no double-spending took place. The response will include a `DepositSuccess`_ object.
:status 401 Unauthorized:
One of the signatures is invalid.
- :status 403:
+ :status 403 Forbidden:
The deposit operation has failed because the coin has insufficient
residual value; the request should not be repeated again with this coin.
In this case, the response is a `DepositDoubleSpendError`_.
@@ -823,7 +823,7 @@ the API during normal operation.
gamma_tp: EddsaPublicKey;
// Specific `gamma` value chosen by the exchange.
- gamma: Integer;
+ gamma: number;
}
diff --git a/api-merchant.rst b/api-merchant.rst
index e8c9c9cd..49d2d74a 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -85,9 +85,16 @@ The Frontent HTTP API
// a timestamp of this deposit permission. It equals just the contract's timestamp
timestamp: Timestamp;
- // same value held in the contract's `refund` field
+ // Deadline for the customer to be refunded for this purchase
refund_deadline: Timestamp;
+ // Deadline for the customer to pay for this purchase. Note that is up to the frontend
+ // to make sure that this value matches the one the backend signed over when the contract
+ // was generated. The frontend should never verify if the payment is still on time,
+ // because when payments are replayed it is expxectable that this deadline is expired,
+ // and only the backend can detect if a payment is a reply or not.
+ pay_deadline: Timestamp;
+
// the chosen exchange's base URL
exchange: string;
@@ -176,10 +183,10 @@ The following API are made available by the merchant's `backend` to the merchant
**Request:**
The `frontend` passes the :ref:`deposit permission <DepositPermission>`
- received from the wallet, and optionally adding a field named `pay_deadline`,
+ received from the wallet, and optionally adding a field named `wire_transfer_deadline`,
indicating a deadline by which he would expect to receive the bank transfer
- for this deal. Note that the `pay_deadline` must be after the `refund_deadline`.
- The backend calculates the `pay_deadline` by adding the `wire_transfer_delay`
+ for this deal. Note that the `wire_transfer_deadline` must be after the `refund_deadline`.
+ The backend calculates the `wire_transfer_deadline` by adding the `wire_transfer_delay`
value found in the configuration to the current time.
**Response:**
@@ -222,6 +229,7 @@ The following API are made available by the merchant's `backend` to the merchant
:query wtid: raw wire transfer identifier identifying the wire transfer (a base32-encoded value)
:query exchange: base URI of the exchange that made the wire transfer
+ :query receiver: identificative token of the merchant :ref:`instance <instances-lab>` which is being tracked.
**Response:**
@@ -234,6 +242,33 @@ The following API are made available by the merchant's `backend` to the merchant
:status 404 Not Found:
The wire transfer identifier is unknown to the exchange.
+ :status 409 Conflict:
+ 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:**
+
+ .. _TransactionConflictProof:
+ .. _tsref-type-TransactionConflictProof:
+ .. code-block:: tsref
+
+ interface TransactionConflictProof {
+ // A claim by the exchange about the transfers associated
+ // with a given wire transfer; it does not list the
+ // transaction that `transaction_tracking_claim` says is part
+ // of the aggregate. This is
+ // a `/track/transfer` response from the exchange.
+ wtid_tracking_claim: TrackTransferResponse;
+
+ // The current claim by the exchange that the given
+ // transaction is included in the above WTID.
+ // (A response from `/track/transaction`).
+ transaction_tracking_claim: TrackTransactionResponse;
+
+ // Public key of the coin for which we got conflicting information.
+ coin_pub: CoinPublicKey;
+
+ }
+
.. http:get:: /track/transaction
Provide the wire transfer identifier associated with an (existing) deposit operation.
@@ -260,6 +295,9 @@ The following API are made available by the merchant's `backend` to the merchant
:status 404 Not Found: The transaction is unknown to the backend.
+ :status 409 Conflict: The exchange provided conflicting information about the transfer.
+ The response body contains the `TrackTransferConflictDetails`_.
+
**Details:**
@@ -293,6 +331,42 @@ The following API are made available by the merchant's `backend` to the merchant
deposit_fee: Amount;
}
+ .. _tsref-type-TrackTransferConflictDetails:
+ .. _TrackTransferConflictDetails:
+ .. code-block:: tsref
+
+ interface TrackTransferConflictDetails {
+ // Text describing the issue for humans.
+ hint: String;
+
+ // A /deposit response matching `coin_pub` showing that the
+ // exchange accepted `coin_pub` for `amount_with_fee`.
+ exchange_deposit_proof: DepositSuccess;
+
+ // Offset in the `exchange_transfer_proof` where the
+ // exchange's response fails to match the `exchange_deposit_proof`.
+ conflict_offset: number;
+
+ // The response from the exchange which tells us when the
+ // coin was returned to us, except that it does not match
+ // the expected value of the coin.
+ exchange_transfer_proof: TrackTransferResponse;
+
+ // Public key of the coin for which we have conflicting information.
+ coin_pub: EddsaPublicKey;
+
+ // Merchant transaction in which `coin_pub` was involved for which
+ // we have conflicting information.
+ transaction_id: number;
+
+ // Expected value of the coin.
+ amount_with_fee: Amount;
+
+ // Expected deposit fee of the coin.
+ deposit_fee: Amount;
+
+ }
+
.. http:get:: /history
Returns transactions up to some point in the past
@@ -314,7 +388,7 @@ The following API are made available by the merchant's `backend` to the merchant
// Hashcode of the relevant contract
h_contract: HashCode;
-
+
// Exchange's base URL
exchange: string;