taler-docs

get-deposits-H_WIRE-MERCHANT_PUB-H_CONTRACT_TERMS-COIN_PUB.rst (4599B)

---

 .. http:get:: /deposits/$H_WIRE/$MERCHANT_PUB/$H_CONTRACT_TERMS/$COIN_PUB
 
   Provide the wire transfer identifier associated with an (existing) deposit operation.
   The arguments are the hash of the merchant's payment details (H_WIRE), the
   merchant's public key (EdDSA), the hash of the contract terms that were paid
   (H_CONTRACT_TERMS) and the public key of the coin used for the payment (COIN_PUB).
 
   **Request:**
 
   :query merchant_sig: EdDSA signature of the merchant made with purpose
     ``TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION`` over a
     ``TALER_DepositTrackPS``, affirming that it is really the merchant who
     requires obtaining the wire transfer identifier.
   :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will wait
     up to ``NUMBER`` milliseconds for completion of a deposit operation before
     sending the HTTP response.
   :query lpt=TARGET: *Optional*.
     Specifies what status change we are long-polling for.
     Use 1 to wait for the a 202 state where ``kyc_ok`` is false *or* a 200 OK response.
     2 to wait exclusively for a 200 OK response.
     @since protocol **v21**.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The deposit has been executed by the exchange and we have a wire transfer identifier.
     The response body is a `TrackTransactionResponse` object.
   :http:statuscode:`202 Accepted`:
     The deposit request has been accepted for processing, but was not yet
     executed.  Hence the exchange does not yet have a wire transfer identifier.  The
     merchant should come back later and ask again.
     The response body is a `TrackTransactionAcceptedResponse`.
   :http:statuscode:`403 Forbidden`:
     A signature is invalid.
     This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`404 Not found`:
     The deposit operation is unknown to the exchange.
 
   **Details:**
 
   .. ts:def:: TrackTransactionResponse
 
     interface TrackTransactionResponse {
 
       // Raw wire transfer identifier of the deposit.
       wtid: Base32;
 
       // When was the wire transfer given to the bank.
       execution_time: Timestamp;
 
       // The contribution of this coin to the total (without fees)
       coin_contribution: Amount;
 
       // Binary-only Signature_ with purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE``
       // over a `TALER_ConfirmWirePS`
       // whereby the exchange affirms the successful wire transfer.
       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: EddsaPublicKey;
     }
 
   .. ts:def:: TrackTransactionAcceptedResponse
 
     interface TrackTransactionAcceptedResponse {
 
       // Legitimization row. Largely useless, except
       // not present if the deposit has not
       // yet been aggregated to the point that a KYC
       // requirement has been evaluated.
       requirement_row?: Integer;
 
       // True if the KYC check for the merchant has been
       // satisfied.  False does not mean that KYC
       // is strictly needed, unless also a
       // legitimization_uuid is provided.
       kyc_ok: boolean;
 
       // Time by which the exchange currently thinks the deposit will be executed.
       // Actual execution may be later if the KYC check is not satisfied by then.
       execution_time: Timestamp;
 
       // Public key associated with the account. The client must sign
       // the initial request for the KYC status using the corresponding
       // private key.  Will be the merchant (instance) public key.
       //
       // This is ONLY given if the merchant did a KYC auth wire transfer.
       // It is not given if the deposit was made to a reserve public key.
       // The wallet would already know the reserve public key, plus there
       // could be various reserve public keys (which do not change), while
       // there is only the *latest* KYC auth wire transfer public key.
       //
       // Absent if no public key is currently associated
       // with the account and the client MUST thus first
       // credit the exchange via an inbound wire transfer
       // to associate a public key with the debited account.
       // Note that absence does *not* imply a need for a KYC auth
       // transfer if the deposit was made to a reserve public key
       // that was also used for the deposit.
       //
       // @since protocol **v20**.
       account_pub?: EddsaPublicKey;
 
     }