get-deposits-H_WIRE-MERCHANT_PUB-H_CONTRACT_TERMS-COIN_PUB.rst (5529B)
1 .. http:get:: /deposits/$H_WIRE/$MERCHANT_PUB/$H_CONTRACT_TERMS/$COIN_PUB 2 3 Provide the wire transfer identifier associated with an (existing) deposit operation. 4 The arguments are the hash of the merchant's payment details (H_WIRE), the 5 merchant's public key (EdDSA), the hash of the contract terms that were paid 6 (H_CONTRACT_TERMS) and the public key of the coin used for the payment (COIN_PUB). 7 8 **Request:** 9 10 :query merchant_sig: EdDSA signature of the merchant made with purpose 11 ``TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION`` over a 12 ``TALER_DepositTrackPS``, affirming that it is really the merchant who 13 requires obtaining the wire transfer identifier. 14 :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will wait 15 up to ``NUMBER`` milliseconds for completion of a deposit operation before 16 sending the HTTP response. 17 :query lpt=TARGET: *Optional*. 18 Specifies what status change we are long-polling for. 19 Use 1 to wait for the a 202 state where ``kyc_ok`` is false *or* a 200 OK response. 20 2 to wait exclusively for a 200 OK response. 21 @since protocol **v21**. 22 23 **Response:** 24 25 :http:statuscode:`200 OK`: 26 The deposit has been executed by the exchange and we have a wire transfer identifier. 27 The response body is a `TrackTransactionResponse` object. 28 :http:statuscode:`202 Accepted`: 29 The deposit request has been accepted for processing, but was not yet 30 executed. Hence the exchange does not yet have a wire transfer identifier. The 31 merchant should come back later and ask again. 32 The response body is a `TrackTransactionAcceptedResponse`. 33 :http:statuscode:`400 Bad request`: 34 A path parameter is malformed. 35 This response comes with a standard `ErrorDetail` response. 36 Possible error codes include 37 ``TALER_EC_EXCHANGE_DEPOSITS_GET_INVALID_H_WIRE``, 38 ``TALER_EC_EXCHANGE_DEPOSITS_GET_INVALID_MERCHANT_PUB``, 39 ``TALER_EC_EXCHANGE_DEPOSITS_GET_INVALID_H_CONTRACT_TERMS``, or 40 ``TALER_EC_EXCHANGE_DEPOSITS_GET_INVALID_COIN_PUB``. 41 :http:statuscode:`403 Forbidden`: 42 The merchant signature is invalid. 43 This response comes with a standard `ErrorDetail` response with 44 a code of ``TALER_EC_EXCHANGE_DEPOSITS_GET_MERCHANT_SIGNATURE_INVALID``. 45 :http:statuscode:`404 Not found`: 46 The deposit operation is unknown to the exchange. 47 This response comes with a standard `ErrorDetail` response with 48 a code of ``TALER_EC_EXCHANGE_DEPOSITS_GET_NOT_FOUND``. 49 :http:statuscode:`500 Internal Server Error`: 50 The exchange had an internal error processing the request. 51 This response comes with a standard `ErrorDetail` response. 52 Possible error codes include 53 ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or 54 ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``. 55 56 **Details:** 57 58 .. ts:def:: TrackTransactionResponse 59 60 interface TrackTransactionResponse { 61 62 // Raw wire transfer identifier of the deposit. 63 wtid: Base32; 64 65 // When was the wire transfer given to the bank. 66 execution_time: Timestamp; 67 68 // The contribution of this coin to the total (without fees) 69 coin_contribution: Amount; 70 71 // Binary-only Signature_ with purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE`` 72 // over a `TALER_ConfirmWirePS` 73 // whereby the exchange affirms the successful wire transfer. 74 exchange_sig: EddsaSignature; 75 76 // Public EdDSA key of the exchange that was used to generate the signature. 77 // Should match one of the exchange's signing keys from /keys. Again given 78 // explicitly as the client might otherwise be confused by clock skew as to 79 // which signing key was used. 80 exchange_pub: EddsaPublicKey; 81 } 82 83 .. ts:def:: TrackTransactionAcceptedResponse 84 85 interface TrackTransactionAcceptedResponse { 86 87 // Legitimization row. Largely useless, except 88 // not present if the deposit has not 89 // yet been aggregated to the point that a KYC 90 // requirement has been evaluated. 91 requirement_row?: Integer; 92 93 // True if the KYC check for the merchant has been 94 // satisfied. False does not mean that KYC 95 // is strictly needed, unless also a 96 // legitimization_uuid is provided. 97 kyc_ok: boolean; 98 99 // Time by which the exchange currently thinks the deposit will be executed. 100 // Actual execution may be later if the KYC check is not satisfied by then. 101 execution_time: Timestamp; 102 103 // Public key associated with the account. The client must sign 104 // the initial request for the KYC status using the corresponding 105 // private key. Will be the merchant (instance) public key. 106 // 107 // This is ONLY given if the merchant did a KYC auth wire transfer. 108 // It is not given if the deposit was made to a reserve public key. 109 // The wallet would already know the reserve public key, plus there 110 // could be various reserve public keys (which do not change), while 111 // there is only the *latest* KYC auth wire transfer public key. 112 // 113 // Absent if no public key is currently associated 114 // with the account and the client MUST thus first 115 // credit the exchange via an inbound wire transfer 116 // to associate a public key with the debited account. 117 // Note that absence does *not* imply a need for a KYC auth 118 // transfer if the deposit was made to a reserve public key 119 // that was also used for the deposit. 120 // 121 // @since protocol **v20**. 122 account_pub?: EddsaPublicKey; 123 124 }