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 Parameters:

• 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.

• 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.

• 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:

200 OK:

The deposit has been executed by the exchange and we have a wire transfer identifier. The response body is a TrackTransactionResponse object.

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.

403 Forbidden:

A signature is invalid. This response comes with a standard ErrorDetail response.

404 Not found:

The deposit operation is unknown to the exchange.

Details:

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;
}

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;

}