diff options
author | Christian Grothoff <christian@grothoff.org> | 2023-05-03 23:15:54 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2023-05-03 23:15:54 +0200 |
commit | 61eba011b5d99314a390eedde2d7041639b1f878 (patch) | |
tree | 9fe715a94eb8a764d73abe731b93adce94a4c44f /core | |
parent | a5ba685d9b5e5dfe7cc7d5f0000325c0803bc9b9 (diff) | |
download | docs-61eba011b5d99314a390eedde2d7041639b1f878.tar.gz docs-61eba011b5d99314a390eedde2d7041639b1f878.tar.bz2 docs-61eba011b5d99314a390eedde2d7041639b1f878.zip |
simplify API to match async processing introduced with #6363
Diffstat (limited to 'core')
-rw-r--r-- | core/api-merchant.rst | 191 |
1 files changed, 3 insertions, 188 deletions
diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 0e1ff018..240bfa77 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -2360,35 +2360,12 @@ Informing the backend about incoming wire transfers **Response:** - :http:statuscode:`200 OK`: - The wire transfer is known to the exchange, details about it follow in the body. - The body of the response is a `MerchantTrackTransferResponse`. - :http:statuscode:`202 Accepted`: - The exchange provided conflicting information about the transfer. Namely, - there is at least one deposit among the deposits aggregated by ``wtid`` - that accounts for a coin whose - details don't match the details stored in merchant's database about the same keyed coin. - The response body contains the `ExchangeConflictDetails`. - This is indicative of a malicious exchange that claims one thing, but did - something else. (With respect to the HTTP specficiation, it is not - precisely that we did not act upon the request, more that the usual - action of filing the transaction as 'finished' does not apply. In - the future, this is a case where the backend actually should report - the bad behavior to the auditor -- and then hope for the auditor to - resolve it. So in that respect, 202 is the right status code as more - work remains to be done for a final resolution.) + :http:statuscode:`204 No content`: + The wire transfer is now confirmed at the merchant. :http:statuscode:`404 Not found`: The instance or account are unknown to the exchange. :http:statuscode:`409 Conflict`: - The wire transfer identifier is already known to us, but for a different amount, - wire method or exchange, or the amount reported by the exchange differs from - the amount reported by the merchant. - :http:statuscode:`502 Bad gateway`: - 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. - :http:statuscode:`504 Gateway timeout`: - The merchant's interaction with the exchange took too long. - The client might want to try again later. + The wire transfer identifier is already known to us, but for a different amount. **Details:** @@ -2408,168 +2385,6 @@ Informing the backend about incoming wire transfers exchange_url: string; } - .. ts:def:: MerchantTrackTransferResponse - - interface MerchantTrackTransferResponse { - // Total amount transferred. - total: Amount; - - // Applicable wire fee that was charged. - wire_fee: Amount; - - // Time of the execution of the wire transfer by the exchange, according to the exchange. - execution_time: Timestamp; - - // Details about the deposits. - deposits_sums: MerchantTrackTransferDetail[]; - } - - .. ts:def:: MerchantTrackTransferDetail - - interface MerchantTrackTransferDetail { - // Business activity associated with the wire transferred amount - // ``deposit_value``. - order_id: string; - - // The total amount the exchange paid back for ``order_id``. - deposit_value: Amount; - - // Applicable fees for the deposit. - deposit_fee: Amount; - } - - - .. ts:def:: ExchangeConflictDetails - - type ExchangeConflictDetails = WireFeeConflictDetails | - TrackTransferConflictDetails; - - - .. ts:def:: WireFeeConflictDetails - - // Note: this is not the full 'proof' of misbehavior, as - // the bogus message from the exchange with a signature - // over the 'different' wire fee is missing. - // - // This information is NOT provided by the current implementation, - // because this would be quite expensive to generate and is - // hardly needed _here_. Once we add automated reports for - // the Taler auditor, we need to generate this data anyway - // and should probably return it here as well. - interface WireFeeConflictDetails { - // Numerical `error code <error-codes>`: - code: "TALER_EC_MERCHANT_PRIVATE_POST_TRANSFERS_BAD_WIRE_FEE"; - - // Text describing the issue for humans. - hint: string; - - // Wire fee (wrongly) charged by the exchange, breaking the - // contract affirmed by the ``exchange_sig``. - wire_fee: Amount; - - // Timestamp of the wire transfer. - execution_time: Timestamp; - - // The expected wire fee (as signed by the exchange). - expected_wire_fee: Amount; - - // Expected closing fee (needed to verify signature). - expected_closing_fee: Amount; - - // Start date of the expected fee structure. - start_date: Timestamp; - - // End date of the expected fee structure. - end_date: Timestamp; - - // Signature of the exchange affirming the expected fee structure. - master_sig: EddsaSignature; - - // Master public key of the exchange. - master_pub: EddsaPublicKey; - } - - - .. ts:def:: TrackTransferConflictDetails - - interface TrackTransferConflictDetails { - // Numerical `error code <error-codes>`. - code: "TALER_EC_MERCHANT_PRIVATE_POST_TRANSFERS_CONFLICTING_REPORTS"; - - // Text describing the issue for humans. - hint: string; - - // Offset in the ``exchange_transfer`` 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. - // - // This field is NOT provided by the current implementation, - // because this would be quite expensive to generate and is - // hardly needed _here_. Once we add automated reports for - // the Taler auditor, we need to generate this data anyway - // and should probably return it here as well. - exchange_transfer?: TrackTransferResponse; - - // Public key of the exchange used to sign the response to - // our deposit request. - deposit_exchange_pub: EddsaPublicKey; - - // Signature of the exchange signing the (conflicting) response. - // Signs over a ``struct TALER_DepositConfirmationPS``. - deposit_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. Needed - // to verify the ``exchange_sig``. - 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; - - // 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; - - } - - .. ts:def:: TrackTransferProof - - interface TrackTransferProof { - // Signature from the exchange made with purpose - // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT``. - exchange_sig: EddsaSignature; - - // Public EdDSA key of the exchange that was used to generate the signature. - // Should match one of the exchange's signing keys from ``/keys``. Again given - // explicitly as the client might otherwise be confused by clock skew as to - // which signing key was used. - exchange_pub: EddsaSignature; - - // Hash of the wire details (identical for all deposits). - // Needed to check the ``exchange_sig`` - h_wire: HashCode; - } - Querying known wire transfers ----------------------------- |