taler-docs

get-transaction-by-id.rst (20665B)

---

 .. ts:op:: getTransactionById
   :read-only:
 
   Get a single transaction by its identifier.
 
   **Request:**
 
     The request ``args`` must be a `TransactionByIdRequest` object.
 
   **Response:**
 
     On success, the result is a `Transaction` object.
 
   **Expected errors:**
 
     The caller can handle the following errors inline:
     ``WALLET_TRANSACTION_NOT_FOUND``, ``WALLET_CORE_API_BAD_REQUEST``.
 
   **Details:**
 
     The ``transactionId`` must have the form of a `TransactionIdStr`;
     malformed identifiers fail with ``WALLET_CORE_API_BAD_REQUEST``,
     well-formed but unknown identifiers with
     ``WALLET_TRANSACTION_NOT_FOUND``.
 
     The full contract terms (``contractTerms``) are only reported for
     payment transactions and only when ``includeContractTerms`` is
     set.
 
 .. ts:def:: Transaction
 
   // A transaction in the wallet's transaction history.  The
   // ``type`` field discriminates the union; all members share the
   // fields of `TransactionCommon`.
   type Transaction =
     | TransactionWithdrawal
     | TransactionPayment
     | TransactionRefund
     | TransactionRefresh
     | TransactionDeposit
     | TransactionPeerPullCredit
     | TransactionPeerPullDebit
     | TransactionPeerPushCredit
     | TransactionPeerPushDebit
     | TransactionInternalWithdrawal
     | TransactionRecoup
     | TransactionDenomLoss;
 
 .. ts:def:: TransactionIdStr
 
   // Opaque, stable identifier of a transaction, of the form
   // ``txn:<type>:<id>`` where ``<type>`` is a `TransactionType`.
   // (The TypeScript source additionally brands this string type;
   // the brand only exists at compile time.)
   type TransactionIdStr = `txn:${string}:${string}`;
 
 .. ts:def:: TransactionType
 
   type TransactionType =
     | "withdrawal"
     | "internal-withdrawal"
     | "payment"
     | "refund"
     | "refresh"
     | "deposit"
     | "peer-push-debit"
     | "peer-push-credit"
     | "peer-pull-debit"
     | "peer-pull-credit"
     | "recoup"
     | "denom-loss";
 
 .. ts:def:: TransactionCommon
 
   interface TransactionCommon {
     // Opaque unique ID for the transaction, used as a starting
     // point for paginating queries and for invoking actions on the
     // transaction (e.g. deleting it from the history).
     transactionId: TransactionIdStr;
 
     // The transaction produced funds under an exchange key set that
     // the user subsequently purged from the wallet.
     legacy?: boolean;
 
     // Short identifier assigned by this wallet for local,
     // human-facing use, of the form ``#<type>:<localIdent>``.
     // Intentionally not portable: importing or merging a wallet can
     // assign different local identifiers.  Clients must use
     // ``transactionId`` when they need a stable ID.  Undefined when
     // the wallet backend does not support local IDs.
     localTransactionId?: string;
 
     // Type of the transaction; discriminates the `Transaction`
     // union.
     type: TransactionType;
 
     // Main timestamp of the transaction.
     timestamp: TalerPreciseTimestamp;
 
     // Scopes of this transaction.
     scopes: ScopeInfo[];
 
     // Transaction state, as per DD37.
     txState: TransactionState;
 
     // Wallet-internal state ID, only used for debugging and
     // testing.
     stId: number;
 
     // Possible transitions based on the current state.
     txActions: TransactionAction[];
 
     // Raw amount of the transaction (exclusive of fees or other
     // extra costs).
     amountRaw: AmountString;
 
     // Amount shown when the transaction was confirmed, including
     // estimated fees.  Preserved when execution fails, expires or
     // is aborted.
     amountEffective: AmountString;
 
     // Settled wallet balance effect, including fees and abort
     // recovery.  Nonnegative; the transaction type determines
     // whether this is a debit or a credit.  Absent until the
     // transaction and its recovery have settled, or when the amount
     // cannot be established for historical records.  Ordinary
     // merchant refunds remain separate credits.  Associated
     // refreshes have zero effect.
     amountEffectiveFinal?: AmountString;
 
     error?: TalerErrorDetail;
 
     abortReason?: TalerErrorDetail;
 
     failReason?: TalerErrorDetail;
 
     // Location where the user must go to complete KYC; present
     // when the transaction's minor state is ``kyc``.
     kycUrl?: string;
 
     // KYC payto hash.  Useful for testing, not so useful for UIs.
     kycPaytoHash?: string;
 
     // KYC access token.  Useful for testing, not so useful for UIs.
     kycAccessToken?: string;
 
     kycAuthTransferInfo?: KycAuthTransferInfo;
   }
 
 .. ts:def:: TransactionState
 
   interface TransactionState {
     // Major state component of the transaction state.
     major: TransactionMajorState;
 
     // Minor state component of the transaction.
     minor?: TransactionMinorState;
 
     // Whether the wallet is currently actively processing the
     // transaction or waiting for a counterparty.  Will eventually
     // be folded into a new major state.
     working?: boolean;
   }
 
 .. ts:def:: TransactionMajorState
 
   type TransactionMajorState =
     // No state, only used when reporting transitions into the
     // initial state.
     | "none"
     | "pending"
     | "done"
     | "aborting"
     | "aborted"
     | "dialog"
     | "finalizing"
     // A suspended pending state.
     | "suspended"
     | "suspended-finalizing"
     | "suspended-aborting"
     | "failed"
     | "expired"
     // Only used for notifications, never in the transaction
     // history.
     | "deleted";
 
 .. ts:def:: TransactionMinorState
 
   type TransactionMinorState =
     | "aborting-bank"
     | "accept-refund"
     | "auto-refund"
     | "balance-kyc"
     | "bank"
     | "bank-confirm-transfer"
     | "bank-register-reserve"
     | "check-refund"
     | "claim-proposal"
     | "completed-by-other-wallet"
     | "continued-with-other-wallet"
     | "create-purse"
     | "delete-purse"
     | "deposit"
     | "deposit-abort-partial"
     | "deposit-abort-recovered"
     | "deposit-abort-recovery-failed"
     | "deposit-abort-refund-failed"
     | "deposit-abort-too-late"
     | "exchange"
     | "exchange-wait-reserve"
     | "kyc-auth"
     | "kyc-hard-limit"
     | "kyc-init"
     | "kyc"
     | "merge"
     | "paid-by-other"
     | "proposed"
     | "ready"
     | "rebind-session"
     | "refresh"
     | "refused"
     | "repurchase"
     | "submit-payment"
     | "track"
     | "unknown"
     | "withdraw"
     | "waiting-for-other-wallet"
     | "abort";
 
 .. ts:def:: TransactionAction
 
   // Actions the user can request on a transaction in its current
   // state; each action corresponds to one of the transaction
   // operations.
   type TransactionAction =
     | "delete"
     | "suspend"
     | "resume"
     | "abort"
     | "fail"
     | "retry";
 
 .. ts:def:: KycAuthTransferInfo
 
   interface KycAuthTransferInfo {
     // Payto URI of the account that must make the transfer.  The
     // KYC auth transfer will *not* work if it originates from a
     // different account.
     debitPaytoUri: string;
 
     // Account public key.  Included in the transfer subject for
     // some of the transfer options.
     accountPub: string;
 
     // Options for making the KYC auth transfer, grouped by exchange
     // credit account in the same format used for withdrawals.
     transferOptionsExt: WithdrawalExchangeAccountDetails[];
 
     // Options for making the KYC auth transfer payment to the
     // exchange.  Deprecated: use ``transferOptionsExt`` instead.
     transferOptions: TransferOption[];
 
     // Validity of the transferOptions, or undefined if they do not
     // expire.  Deprecated: use the per-account expiry in
     // ``transferOptionsExt`` instead.
     transferExpiry: TalerProtocolTimestamp | undefined;
 
     // Amount that the exchange expects to be deposited.  Usually
     // the smallest amount that can be transferred via a bank
     // transfer.  Deprecated: use ``transferOptions`` instead.
     amount: AmountString;
 
     // Possible target payto URIs.  Deprecated: use
     // ``transferOptions`` instead.
     creditPaytoUris: string[];
   }
 
 .. ts:def:: TransactionWithdrawal
 
   // A withdrawal transaction (either bank-integrated or manual).
   interface TransactionWithdrawal extends TransactionCommon {
     type: "withdrawal";
 
     // Exchange of the withdrawal.
     exchangeBaseUrl: string | undefined;
 
     // Amount that got subtracted from the reserve balance.
     amountRaw: AmountString;
 
     // Amount that actually was (or will be) added to the wallet's
     // balance.
     amountEffective: AmountString;
 
     withdrawalDetails: WithdrawalDetails;
   }
 
 .. ts:def:: TransactionInternalWithdrawal
 
   // Internal withdrawal operation, only reported on request.  Some
   // transactions (peer-*-credit) internally do a withdrawal, but
   // only the peer-*-credit transaction is reported.  The internal
   // withdrawal transaction gives access to the details of the
   // underlying withdrawal for testing/debugging.  It is usually not
   // reported, so that the amounts of transactions properly add up.
   interface TransactionInternalWithdrawal extends TransactionCommon {
     type: "internal-withdrawal";
 
     // Exchange of the withdrawal.
     exchangeBaseUrl: string;
 
     // Amount that got subtracted from the reserve balance.
     amountRaw: AmountString;
 
     // Amount that actually was (or will be) added to the wallet's
     // balance.
     amountEffective: AmountString;
 
     withdrawalDetails: WithdrawalDetails;
   }
 
 .. ts:def:: WithdrawalDetails
 
   type WithdrawalDetails =
     | WithdrawalDetailsForManualTransfer
     | WithdrawalDetailsForTalerBankIntegrationApi;
 
 .. ts:def:: WithdrawalDetailsForManualTransfer
 
   interface WithdrawalDetailsForManualTransfer {
     type: "manual-transfer";
 
     // Payto URIs that the exchange supports.  Already contains the
     // amount and message.  Deprecated: in favor of
     // ``exchangeCreditAccountDetails``.
     exchangePaytoUris: string[];
 
     exchangeCreditAccountDetails?: WithdrawalExchangeAccountDetails[];
 
     // Public key of the reserve.
     reservePub: string;
 
     // Is the reserve ready for withdrawal?
     reserveIsReady: boolean;
 
     // How long the exchange waits to transfer back funds from a
     // reserve.
     reserveClosingDelay: TalerProtocolDuration;
   }
 
 .. ts:def:: WithdrawalDetailsForTalerBankIntegrationApi
 
   interface WithdrawalDetailsForTalerBankIntegrationApi {
     type: "taler-bank-integration-api";
 
     // True if the bank has confirmed the withdrawal.  An
     // unconfirmed withdrawal usually requires user input and should
     // be highlighted in the UI; see ``bankConfirmationUrl``.
     confirmed: boolean;
 
     // If the withdrawal is unconfirmed, this can include a URL for
     // user-initiated confirmation.
     bankConfirmationUrl?: string;
 
     // Public key of the reserve.
     reservePub: string;
 
     // Is the reserve ready for withdrawal?
     reserveIsReady: boolean;
 
     // Is the bank transfer for the withdrawal externally
     // confirmed?
     externalConfirmation?: boolean;
 
     exchangeCreditAccountDetails?: WithdrawalExchangeAccountDetails[];
   }
 
 .. ts:def:: TransactionPayment
 
   interface TransactionPayment extends TransactionCommon {
     type: "payment";
 
     // Merchant instance base URL used to claim the order.
     // Available even before the contract terms have been
     // downloaded.
     merchantBaseUrl: string;
 
     // Public payment URI shown while this wallet waits for another
     // wallet to claim an order that it released.
     unclaimedPayUri?: TalerUriString;
 
     // Additional information about the payment.  Only present if
     // the information about the order is already available.
     info: OrderShortInfo | undefined;
 
     // Full contract terms.  Only included if explicitly requested
     // via the ``includeContractTerms`` flag of
     // ``getTransactionById``.
     contractTerms?: MerchantContractTerms;
 
     // Amount that must be paid for the contract.
     amountRaw: AmountString;
 
     // Amount that was paid, including deposit, wire and refresh
     // fees.
     amountEffective: AmountString;
 
     // Amount that has been refunded by the merchant.
     totalRefundRaw: AmountString;
 
     // Amount that will be added to the wallet's balance after fees
     // and refreshing.
     totalRefundEffective: AmountString;
 
     // Amount pending to be picked up.
     refundPending: AmountString | undefined;
 
     // Reference to applied refunds.
     refunds: RefundInfoShort[];
 
     // Is the wallet currently checking for a refund?
     refundQueryActive: boolean;
 
     // PoS confirmation codes, separated by newlines.  Only present
     // for purchases that support PoS confirmation.
     posConfirmation: string | undefined;
 
     // Until when the ``posConfirmation`` is valid.
     posConfirmationDeadline?: TalerProtocolTimestamp;
 
     // Did we receive the payment via a taler://pay-template/ URI
     // and did the URI contain a nfc=1 flag?
     posConfirmationViaNfc?: boolean;
 
     // In case this payment transaction was detected as a
     // repurchase, the transaction ID of the original payment.
     repurchaseTransactionId?: TransactionIdStr;
 
     // If applicable, the choice that the user selected.
     choiceIndex?: number;
   }
 
 .. ts:def:: OrderShortInfo
 
   interface OrderShortInfo {
     // Order ID, uniquely identifies the order within a merchant
     // instance.
     orderId: string;
 
     // Hash of the contract terms.
     contractTermsHash: string;
 
     // More information about the merchant.
     merchant: MerchantInfo;
 
     // Summary of the order, given by the merchant.
     summary: string;
 
     // Map from IETF BCP 47 language tags to localized summaries.
     summary_i18n?: InternationalizedString;
 
     // URL of the fulfillment, given by the merchant.
     fulfillmentUrl?: string;
 
     // Plain text message that should be shown to the user when the
     // payment is complete.
     fulfillmentMessage?: string;
 
     // Translations of ``fulfillmentMessage``.
     fulfillmentMessage_i18n?: InternationalizedString;
   }
 
 .. ts:def:: RefundInfoShort
 
   interface RefundInfoShort {
     transactionId: string;
 
     timestamp: TalerProtocolTimestamp;
 
     amountEffective: AmountString;
 
     amountRaw: AmountString;
   }
 
 .. ts:def:: TransactionRefund
 
   interface TransactionRefund extends TransactionCommon {
     // Recovery already included in the unsuccessful payment's
     // final cost.
     isAbortRecovery?: boolean;
 
     type: "refund";
 
     // Amount that has been refunded by the merchant.
     amountRaw: AmountString;
 
     // Amount that will be added to the wallet's balance after fees
     // and refreshing.
     amountEffective: AmountString;
 
     // ID of the transaction that is refunded.
     refundedTransactionId: string;
 
     paymentInfo: RefundPaymentInfo | undefined;
   }
 
 .. ts:def:: RefundPaymentInfo
 
   // Summary information about the payment that we got a refund
   // for.
   interface RefundPaymentInfo {
     summary: string;
 
     summary_i18n?: InternationalizedString;
 
     // More information about the merchant.
     merchant: MerchantInfo;
   }
 
 .. ts:def:: TransactionRefresh
 
   // A transaction shown for refreshes.  Only shown for (1)
   // refreshes not associated with other transactions and (2)
   // refreshes in an error state.
   interface TransactionRefresh extends TransactionCommon {
     type: "refresh";
 
     refreshReason: RefreshReason;
 
     // Transaction ID that caused this refresh.
     originatingTransactionId?: string;
 
     // Always zero for refreshes.
     amountRaw: AmountString;
 
     // Fees, i.e. the effective, negative effect of the refresh on
     // the balance.  Only applicable for stand-alone refreshes, and
     // zero for other refreshes where the transaction itself
     // accounts for the refresh fee.
     amountEffective: AmountString;
 
     refreshInputAmount: AmountString;
 
     refreshOutputAmount: AmountString;
   }
 
 .. ts:def:: RefreshReason
 
   // Reason why a coin is being refreshed.
   type RefreshReason =
     | "manual"
     | "pay-merchant"
     | "pay-deposit"
     | "pay-peer-push"
     | "pay-peer-pull"
     | "refund"
     | "abort-pay"
     | "abort-deposit"
     | "abort-peer-push-debit"
     | "abort-peer-pull-debit"
     | "recoup"
     | "backup-restored"
     | "scheduled";
 
 .. ts:def:: TransactionDeposit
 
   // Deposit transaction, which effectively sends money from this
   // wallet somewhere else.
   interface TransactionDeposit extends TransactionCommon {
     type: "deposit";
 
     depositGroupId: string;
 
     // Target for the deposit.
     targetPaytoUri: string;
 
     // Raw amount that is being deposited.
     amountRaw: AmountString;
 
     // Deposit account public key.
     accountPub: string;
 
     // Effective amount that is being deposited.
     amountEffective: AmountString;
 
     wireTransferDeadline: TalerProtocolTimestamp;
 
     wireTransferProgress: number;
 
     // Did all the deposit requests succeed?
     deposited: boolean;
 
     trackingState: Array<DepositTransactionTrackingState>;
   }
 
 .. ts:def:: DepositTransactionTrackingState
 
   interface DepositTransactionTrackingState {
     // Raw wire transfer identifier of the deposit.
     wireTransferId: string;
 
     // When the wire transfer was given to the bank.
     timestampExecuted: TalerProtocolTimestamp;
 
     // Total amount transferred for this wtid (including fees).
     amountRaw: AmountString;
 
     // Wire fee amount for this exchange.
     wireFee: AmountString;
   }
 
 .. ts:def:: TransactionPeerPullCredit
 
   // Credit because we were paid for a P2P invoice we created.
   interface TransactionPeerPullCredit extends TransactionCommon {
     type: "peer-pull-credit";
 
     info: PeerInfoShort;
 
     // Exchange used.
     exchangeBaseUrl: string;
 
     // Amount that got subtracted from the reserve balance.
     amountRaw: AmountString;
 
     // Amount that actually was (or will be) added to the wallet's
     // balance.
     amountEffective: AmountString;
 
     // URI to send to the other party.  Only available in the right
     // state.
     talerUri: string | undefined;
   }
 
 .. ts:def:: TransactionPeerPullDebit
 
   // Debit because we paid someone's invoice.
   interface TransactionPeerPullDebit extends TransactionCommon {
     type: "peer-pull-debit";
 
     info: PeerInfoShort;
 
     // Exchange used.
     exchangeBaseUrl: string;
 
     amountRaw: AmountString;
 
     amountEffective: AmountString;
   }
 
 .. ts:def:: TransactionPeerPushDebit
 
   // We sent money via a P2P payment.
   interface TransactionPeerPushDebit extends TransactionCommon {
     type: "peer-push-debit";
 
     info: PeerInfoShort;
 
     // Exchange used.
     exchangeBaseUrl: string;
 
     // Amount that got subtracted from the reserve balance.
     amountRaw: AmountString;
 
     // Amount that actually was (or will be) added to the wallet's
     // balance.
     amountEffective: AmountString;
 
     // URI to accept the payment.  Only present if the transaction
     // is in a state where the other party can accept the payment.
     talerUri?: string;
   }
 
 .. ts:def:: TransactionPeerPushCredit
 
   // We received money via a P2P payment.
   interface TransactionPeerPushCredit extends TransactionCommon {
     type: "peer-push-credit";
 
     info: PeerInfoShort;
 
     // Exchange used.
     exchangeBaseUrl: string;
 
     // Amount that got subtracted from the reserve balance.
     amountRaw: AmountString;
 
     // Amount that actually was (or will be) added to the wallet's
     // balance.
     amountEffective: AmountString;
   }
 
 .. ts:def:: PeerInfoShort
 
   interface PeerInfoShort {
     expiration: TalerProtocolTimestamp | undefined;
 
     summary: string | undefined;
 
     iconId: string | undefined;
   }
 
 .. ts:def:: TransactionRecoup
 
   // The exchange revoked a key and the wallet recoups funds.
   interface TransactionRecoup extends TransactionCommon {
     type: "recoup";
   }
 
 .. ts:def:: TransactionDenomLoss
 
   // A transaction to indicate financial loss due to denominations
   // that became unusable for deposits.
   interface TransactionDenomLoss extends TransactionCommon {
     type: "denom-loss";
 
     lossEventType: DenomLossEventType;
 
     exchangeBaseUrl: string;
   }
 
 .. ts:def:: DenomLossEventType
 
   type DenomLossEventType =
     | "denom-expired"
     | "denom-vanished"
     | "denom-unoffered"
     // The exchange revoked the denomination.  A revoked
     // denomination also stops being offered, so this must be
     // checked before "denom-unoffered" to say what actually
     // happened.
     | "denom-revoked";
 
 .. ts:def:: TransactionByIdRequest
 
   interface TransactionByIdRequest {
     transactionId: string;
 
     // If set to true, report the full contract terms in the
     // response if the transaction has them.
     includeContractTerms?: boolean;
   }