> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iterapay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Transactions: On-Chain Payment Events Explained
> Transactions record on-chain payment events against your invoices. Learn about transaction states, how they relate to invoices, and how to search them.
A transaction is IteraPay's record of an on-chain payment event. When a customer sends cryptocurrency to a deposit address generated by one of your invoices, IteraPay detects that transfer on the blockchain and creates a transaction to represent it. Transactions are immutable records — they capture what happened on-chain and link that event back to the invoice that generated the deposit address.
## What a transaction records
Each transaction captures:
* **The amount received**, in the token's native units and USD equivalent
* **The associated invoice**, identified by invoice ID and type
* **The transaction state**, reflecting where in the confirmation and settlement pipeline the payment sits
* **On-chain identifiers** such as the transaction hash, which you can use to verify the payment on a block explorer
## Transaction states
Transactions move through states as the payment progresses from detection to settlement. The exact states reflect the confirmation depth and AML screening outcome for the payment.
IteraPay has detected the transaction on-chain but it has not yet reached the required number of block confirmations. Funds are not yet available.
The transaction has reached the required confirmation threshold. AML screening may still be in progress.
The payment has passed AML checks and the funds are available in the invoice balance, ready to be collected into your merchant account.
The transaction was rejected — either due to AML screening failure or another processing error. Flagged funds are held pending review.
You do not need to poll transaction states manually. Configure [webhooks](/guides/webhooks) to receive real-time notifications when a transaction's state changes.
## Relationship between transactions and invoices
Every transaction belongs to exactly one invoice. The invoice type determines what the transaction means in your flow:
| Invoice type | What the transaction represents |
| ------------ | ------------------------------------------------------------------------ |
| `onetime` | A customer's single payment against a specific order or request |
| `reusable` | One of potentially many payments collected through a shared payment link |
| `collect` | An internal sweep of settled funds into your merchant balance |
| `withdraw` | An outbound transfer from your merchant balance to an external address |
Because multiple transactions can exist against a single reusable invoice, use the related invoices endpoint to find all invoices associated with a set of transactions filtered by type:
```http theme={null}
GET /merchants/{merchantID}/transactions/related_invoices?type=reusable
```
The `type` parameter accepts `onetime`, `reusable`, `collect`, or `withdraw`.
## Retrieving a single transaction
If you have a transaction ID, you can fetch its full details directly:
```http theme={null}
GET /merchants/{merchantID}/transactions/{transactionID}
```
## Searching and filtering transactions
For bulk retrieval and reporting, use the list endpoint. This endpoint accepts a request body with filter and pagination parameters:
```http theme={null}
POST /merchants/{merchantID}/transactions/list
```
**Example request body:**
```json theme={null}
{
"invoiceType": "onetime",
"state": "settled",
"dateFrom": "2026-01-01T00:00:00Z",
"dateTo": "2026-04-30T23:59:59Z",
"page": 1,
"pageSize": 50
}
```
Use `POST` (not `GET`) for the transaction list endpoint. This lets you pass complex filter objects in the request body without URL length constraints.
**Supported filters:**
| Field | Description |
| ------------------------- | -------------------------------------------------------------------- |
| `invoiceType` | Filter by invoice type: `onetime`, `reusable`, `collect`, `withdraw` |
| `state` | Filter by transaction state |
| `methodID` | Filter by payment method (cryptocurrency) |
| `amountMin` / `amountMax` | Filter by transaction amount range in USD |
| `dateFrom` / `dateTo` | Filter by transaction timestamp range |
| `invoiceID` | Filter to transactions for a specific invoice |
| `page` / `pageSize` | Pagination controls |
## Common patterns
**Reconciliation**: Use the list endpoint filtered by `state: "settled"` and a date range to pull all settled transactions for a period and reconcile them against your records.
**Investigating a payment**: Use `GET /merchants/{merchantID}/transactions/{transactionID}` with the transaction ID from a webhook payload to retrieve full details when responding to a payment event.
**Auditing withdrawals**: Filter the list endpoint by `invoiceType: "withdraw"` to see all outbound transfers from your merchant balance.
## Related reference
Search and filter transactions with pagination.
Retrieve a single transaction by ID.
Understand how invoices generate the deposit addresses that transactions are recorded against.
Receive real-time notifications when transaction states change.