summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-05-09 17:50:33 +0200
committerChristian Grothoff <christian@grothoff.org>2020-05-09 17:50:33 +0200
commit38df5382734bcf4de85c0f65e27a1b8800594ad9 (patch)
treed7cf8fc08daa8eba56073999c3a876ee4bba3bbd
parent09dc4b08107c8669ad4c1c2d5c00f2315329afc0 (diff)
downloaddocs-38df5382734bcf4de85c0f65e27a1b8800594ad9.tar.gz
docs-38df5382734bcf4de85c0f65e27a1b8800594ad9.tar.bz2
docs-38df5382734bcf4de85c0f65e27a1b8800594ad9.zip
update/clarify spec
-rw-r--r--core/api-exchange.rst8
-rw-r--r--core/api-merchant.rst96
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``.