[taler-docs] branch master updated: update/clarify spec

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 38df538  update/clarify spec
     new 864be01  Merge branch 'master' of git+ssh://git.taler.net/docs
38df538 is described below

commit 38df5382734bcf4de85c0f65e27a1b8800594ad9
Author: Christian Grothoff <address@hidden>
AuthorDate: Sat May 9 17:50:33 2020 +0200

    update/clarify spec
---
 core/api-exchange.rst |  8 ++---
 core/api-merchant.rst | 96 +++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 89 insertions(+), 15 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 2fbdfbb..ea735ed 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -661,10 +661,7 @@ denomination.
       // exchange's unblinded RSA signature of the coin
       ub_sig: RsaSignature;
 
-      // timestamp when the contract was finalized, must match approximately 
the
-      // current time of the exchange; if the timestamp is too far off, the
-      // exchange returns "400 Bad Request" with an error code of
-      // "TALER_EC_DEPOSIT_INVALID_TIMESTAMP".
+      // timestamp when the contract was finalized.
       timestamp: Timestamp;
 
       // indicative time by which the exchange undertakes to transfer the 
funds to
@@ -701,6 +698,9 @@ denomination.
       // URL, or if the base URL has changed since the deposit.
       transaction_base_url?: string;
 
+      // timestamp when the deposit was received by the exchange.
+      exchange_timestamp: Timestamp;
+
       // the EdDSA signature of `TALER_DepositConfirmationPS` using a current
       // `signing key of the exchange <sign-key-priv>` affirming the successful
       // deposit and that the exchange will transfer the funds after the refund
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 26c8175..f2a0944 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1186,9 +1186,13 @@ Receiving Payments
 
   .. ts:def:: PublicPayStatusResponse
 
-    interface PublicPayStatusResponse {
+    type PublicPayStatusResponse = StatusPaid | StatusUnpaid
+
+  .. ts:def:: StatusPaid
+
+    interface StatusPaid {
       // Has the payment for this order (ever) been completed?
-      paid: boolean;
+      paid: true;
 
       // Was the payment refunded (even partially, via refund or abort)?
       refunded: boolean;
@@ -1197,7 +1201,15 @@ Receiving Payments
       refund_amount: Amount;
 
       // Successful refunds for this payment, empty array for none.
-      refunds: RefundDetail[];
+      refunds: RefundStatus[];
+
+    }
+
+  .. ts:def:: StatusUnpaid
+
+    interface StatusUnpaid {
+      // Has the payment for this order (ever) been completed?
+      paid: false;
 
       // URI that the wallet must process to complete the payment.
       taler_pay_uri: string;
@@ -1208,12 +1220,47 @@ Receiving Payments
 
     }
 
-  .. ts:def:: RefundDetail
+
+  .. ts:def:: RefundStatus
+
+    type RefundStatus = RefundFailure | RefundConfirmation
+
+
+  .. ts:def:: RefundFailure
+
+    // Details about why a refund failed.
+    interface RefundFailure {
+
+      // HTTP status of the exchange request, must NOT be 200.
+      exchange_status: Integer;
+
+      // Taler error code from the exchange reply, if available.
+      exchange_code?: Integer;
+
+      // If available, HTTP reply from the exchange.
+      exchange_reply?: json;
+
+      // Refund transaction ID.
+      rtransaction_id: Integer;
+
+      // public key of a coin that was refunded
+      coin_pub: EddsaPublicKey;
+
+      // Amount that was refunded, including refund fee charged by the exchange
+      // to the customer.
+      refund_amout: Amount;
+
+    }
+
+  .. ts:def:: RefundConfirmation
 
     // Additional details needed to verify the refund confirmation signature
     // (``h_contract_terms`` and ``merchant_pub``) are already known
     // to the wallet and thus not included.
-    interface RefundDetail {
+    interface RefundConfirmation {
+
+      // HTTP status of the exchange request, 200 required for refund 
confirmations.
+      exchange_status: 200;
 
       // the EdDSA :ref:`signature` (binary-only) with purpose
       // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key 
of the
@@ -1349,6 +1396,8 @@ Tracking Wire Transfers
     The exchange returned an error when we asked it about the "GET /transfer" 
status
     for this wire transfer. Details of the exchange error are returned.
 
+  **Details:**
+
   .. ts:def:: TransferInformation
 
     interface TransferInformation {
@@ -1397,8 +1446,6 @@ Tracking Wire Transfers
     }
 
 
-  **Details:**
-
   .. ts:def:: TrackTransferConflictDetails
 
     interface TrackTransferConflictDetails {
@@ -1421,8 +1468,23 @@ Tracking Wire Transfers
       // the expected value of the coin.
       exchange_transfer: TrackTransferResponse;
 
-      // Proof data we have for the ``exchange_transfer`` data (signatures 
from exchange)
-      exchange_proof: TrackTransferProof;
+      // Public key of the exchange used to sign the response
+      exchange_pub: EdDSAPublicKey;
+
+      // Signature of the exchange signing the (conflicting) response
+      exchange_sig: EdDSASignature;
+
+      // Hash of the merchant's bank account the wire transfer went to
+      h_wire: HashCode;
+
+      // Hash of the contract terms with the conflicting deposit.
+      h_contract_terms: HashCode;
+
+      // At what time the exchange received the deposit.
+      deposit_timestamp: Timestamp;
+
+      // At what time the refund possibility expired (needed to verify 
``exchange_sig``).
+      refund_deadline: Timestamp;
 
       // Public key of the coin for which we have conflicting information.
       coin_pub: EddsaPublicKey;
@@ -1431,9 +1493,15 @@ Tracking Wire Transfers
       // we have conflicting information.
       transaction_id: number;
 
-      // Expected value of the coin.
+      // Amount the exchange counted the coin for in the transfer.
       amount_with_fee: Amount;
 
+      // Expected value of the coin.
+      coin_value: Amount;
+
+      // Expected deposit fee of the coin.
+      coin_fee: Amount;
+
       // Expected deposit fee of the coin.
       deposit_fee: Amount;
 
@@ -1466,12 +1534,18 @@ Tracking Wire Transfers
   **Request:**
 
    :query payto_uri: *Optional*. Filter for transfers to the given bank 
account (subject and amount MUST NOT be given in the payto URI)
+
    :query before: *Optional*. Filter for transfers executed before the given 
timestamp
+
    :query after: *Optional*. Filter for transfers executed after the given 
timestamp
+
    :query limit: *Optional*. At most return the given number of results. 
Negative for descending in execution time, positive for ascending in execution 
time.
+
    :query offset: *Optional*. Starting transfer_serial_id for an iteration.
+
    :query verified: *Optional*. Filter transfers by verification status.
 
+
   **Response:**
 
   :status 200 OK:
@@ -1497,7 +1571,7 @@ Tracking Wire Transfers
       payto_uri: string;
 
       // base URL of the exchange that made the wire transfer
-      exchange: string;
+      exchange_url: string;
 
       // Serial number identifying the transfer in the merchant backend.
       // Used for filgering via ``offset``.

-- 
To stop receiving notification emails like this one, please contact
address@hidden.