Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.iterapay.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 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 typeWhat the transaction represents
onetimeA customer’s single payment against a specific order or request
reusableOne of potentially many payments collected through a shared payment link
collectAn internal sweep of settled funds into your merchant balance
withdrawAn 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: 
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: 
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: 
POST /merchants/{merchantID}/transactions/list
Example request body: 
{
  "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:
FieldDescription
invoiceTypeFilter by invoice type: onetime, reusable, collect, withdraw
stateFilter by transaction state
methodIDFilter by payment method (cryptocurrency)
amountMin / amountMaxFilter by transaction amount range in USD
dateFrom / dateToFilter by transaction timestamp range
invoiceIDFilter to transactions for a specific invoice
page / pageSizePagination 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.

List transactions

Search and filter transactions with pagination.

Get transaction

Retrieve a single transaction by ID.

Invoices

Understand how invoices generate the deposit addresses that transactions are recorded against.

Webhooks

Receive real-time notifications when transaction states change.