Transactions

Every movement on your accounts, how they add up to the balance, and the event they emit.

A transaction is one movement of money on one of your team's accounts. It has one currency: the account it belongs to. List transactions with GET /transactions and read one with GET /transactions/{id}. Both need the transactions:read scope.

Transaction IDs have the form transaction_<uuid>_in or transaction_<uuid>_out. The suffix identifies the side of the movement.

Types

Type	Meaning
`deposit`	A bank transfer into the account.
`payout`	A payout the team sent.
`payment`	A payout the team received on the account. A payout paid to a bank account or PayPal is not an account movement and is not listed.
`fee`	A Talentir fee, charged with the payout in `payoutIds` or as a monthly plan fee.
`transfer`	An on-chain transfer that no payout or deposit explains.

Statuses

Status	Meaning
`pending`	The on-chain transfer is not indexed yet. A deposit is `pending` from the bank arrival until Talentir has sent the stablecoin; a payout from the request until the money leaves the account.
`completed`	The on-chain transfer is indexed and the balance has moved. `completedAt` is when it was mined. A payout on a bank or PayPal rail is `completed` when the money leaves the account, before the bank confirms delivery; `payout.completed` reports the delivery.
`failed`	The money will never move: a cancelled payout, or a rejected or refunded deposit.

type and status are open enums: treat a value you do not know as a fallback case.

Balance

amount is unsigned. direction gives the sign: in adds amount to the account, out takes it away. The sum of all completed transactions of a currency, signed by direction, equals balance.total of that account in GET /team/accounts. pending and failed transactions do not count.

A transfer between two of your team's wallets has an outgoing transaction and an incoming transaction. Both have the same txHash, but distinct IDs. Their amounts cancel out, so the transfer does not change the account balance. Each side sends its own transaction.created event.

Payouts

payoutIds lists the payouts of your team that a transaction settles or charges for.

A payout transaction lists the payouts it settles. One transfer can settle several payouts, so the list can have more than one entry.
A fee transaction lists the payouts it was charged for. A monthly plan fee has an empty list.
deposit, payment, and transfer transactions have an empty list.

To find every transaction of one payout, filter GET /transactions by payoutId.

counterpartyId is the counterparty those payouts go to. It is null when the transaction is not tied to a payout, and when one transfer paid payouts to several counterparties.

txHash is the hash of the on-chain transaction. It is null while the money has not moved on-chain.

Deposits

A deposit carries where the money came from. account is the sender's bank account in the same shape as a counterparty's payment method, plus the account holder as the bank reported it. The variant is the one a counterparty with that account would be saved in:

Sender	`account.type`
A US ACH deposit	`bank_ach` with the sender bank's `routingNumber`; US banks do not report the account number
A US domestic wire	`bank_wire` with the sender bank's `routingNumber`
An international wire into the US account	`bank_swift` with `accountNumber`, `bic`, and `bankCountry`
A UK account paying GBP, reported as a GB IBAN	`bank_uk` with `sortCode` and `accountNumber`
Any other IBAN: SEPA, CHF, a UK account paying EUR, a GBP sender with a non-UK IBAN	`bank_iban`
Anything else, for example a hand-recorded deposit	`bank_swift` with `bankCountry` when known

reference is the payment reference on the transfer. Both fields are null on every other type.

Documents

documents lists the PDFs that account for the transaction, each with a type, the number printed on it, a download url, and the issuedAt date.

A payout or payment carries the recipient's invoice once it exists: a self_billing_invoice that Talentir issued in the recipient's name, or a recipient_invoice the recipient uploaded.
A fee carries Talentir's fee_invoice.
A deposit or transfer has no documents.

The list is empty until the document is issued, which can be after the transaction is completed. The payout endpoints return the same documents as senderInvoiceUrl and recipientInvoiceUrl.

Event

transaction.created fires once per transaction, when the on-chain transfer behind it is final. The indexer confirms a transfer a few minutes after it is mined, so the event follows the balance change, not the payout's status change. data is the transaction as GET /transactions/{id} returns it, with status completed. A pending or failed transaction sends nothing; listen to payout.failed for a failed payout.

Subscribe with transaction.* or transaction.created. The webhook needs transactions:read. See Set up webhooks.