> ## Documentation Index > Fetch the complete documentation index at: https://docs.incard.com/llms.txt > Use this file to discover all available pages before exploring further. # Transactions > List, filter, and page through transactions; read the running balance. Transactions are served by the Incard transactions service through the Developer Gateway under `/developer/transactions`. Every request needs `Authorization: Bearer ` and `X-On-Behalf-Of: ` — see [Authentication](/guides/authentication). ## Endpoints | Method | Path | Purpose | | ------ | ------------------------------ | ---------------------------------------------- | | `GET` | `/developer/transactions` | List transactions with filters and pagination. | | `GET` | `/developer/transactions/{id}` | Fetch one transaction by UUID. | ## List transactions ```bash theme={null} curl -sS "https://api.incard.com/developer/transactions?status=completed&from=2026-07-01T00:00:00Z&to=2026-07-31T23:59:59Z&limit=50" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "X-On-Behalf-Of: YOUR_COMPANY_ID" ``` Response (truncated): ```json theme={null} { "transactions": [ { "id": "342ea759-8870-418a-aa4c-ebc3a93ff70d", "source_payment_id": "ab8861be-020f-6449-655e-c7b00ff71b74", "company_id": "bebb185d-8210-4e66-ac63-397b49a1e09f", "account_id": "0d6c0a2a-2b08-49bc-89a9-eb936c9ff28c", "name": "ACME Corp", "status": "completed", "type": "out", "direction": "debit", "transaction_at": "2026-07-02T16:07:39.917Z", "account_amount": { "value": "-300.00", "currency": "GBP" }, "running_balance": { "value": "4700.00", "currency": "GBP" }, "created_at": "2026-07-02T16:07:39.970773Z", "updated_at": "2026-07-02T16:08:11.120114Z" } ], "next_cursor": "eyJzb3J0IjoidHJhbnNhY3Rpb25fYXQiLCJkaXJlY3Rpb24iOi..." } ``` Results are sorted by `transaction_at` descending unless you pass `sort` and `order`. ### What the list includes by default * Every status, including `pending` and `declined`, so in-flight payments are visible. * Only accounts the API key's member can access. Members without account scopes see an empty list. * **Excluded** unless you filter for them explicitly with `type`: the reward types `loyalty_out`, `points_in`, `points_out`, and `trophy`. * **Excluded** unless `scheduled=true`: payments scheduled for a future date. * Looking rows up by `ids` or `source_payment_ids` bypasses both exclusions. ### Filters All list filters accept comma-separated values where noted. | Parameter | Notes | | ------------------------------------------------------ | --------------------------------------------------------------------------------- | | `account_ids` | Account UUIDs (comma-separated). | | `account_currencies`, `transaction_currencies` | ISO 4217 codes (comma-separated). | | `status` | `pending`, `completed`, `declined`, `reversed` (comma-separated). | | `type` | Transaction types (comma-separated). See [Transaction types](#transaction-types). | | `direction` | `debit`, `credit`. | | `from`, `to` | Inclusive RFC 3339 bounds on `transaction_at`. | | `account_amount_min`, `account_amount_max` | Absolute amount bounds as decimal strings. | | `q` | Case-insensitive substring match on `name` and `reference`. | | `ids`, `source_payment_ids` | Exact lookups (comma-separated). | | `user_ids`, `payee_ids`, `card_tokens`, `category_ids` | Related-entity filters (comma-separated). | | `categorized` | `true` or `false`. | | `scheduled` | `true` to list upcoming scheduled payments instead. | | `earned_points` | `true` for point-earning transactions only; adds `points_totals_by_day`. | Invalid values return **400** with `{ "error": "" }`. ### Pagination Use **cursor pagination** for syncs and exports. Each page of `limit` rows (default 50, max 200) includes `next_cursor` when more rows exist. Pass it back as `cursor` with the same filters: ```bash theme={null} curl -sS "https://api.incard.com/developer/transactions?limit=200&cursor=NEXT_CURSOR" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "X-On-Behalf-Of: YOUR_COMPANY_ID" ``` The cursor encodes the sort field and order, so do not change `sort` or `order` mid-walk. `next_cursor` is absent on the last page. **Offset pagination** (`offset`) is available for UI-style paging and adds a `total` count to the response. `cursor` and `offset` cannot be combined. ### Enrichment Add `user=true` to include the initiating user's name and avatar, and `card=true` to include the card's name, last four digits, and type on card transactions. Recognised merchants always include `enriched_merchant` with a display name, category, and icon. ## Get a transaction ```bash theme={null} curl -sS "https://api.incard.com/developer/transactions/342ea759-8870-418a-aa4c-ebc3a93ff70d?card=true" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "X-On-Behalf-Of: YOUR_COMPANY_ID" ``` Returns the transaction object directly (no envelope). You get **404** if the transaction belongs to another company or to an account the member cannot access. ## Amounts and signs Every amount is a `{ "value": "", "currency": "" }` object. Values are **signed**: `debit` transactions are negative and `credit` transactions positive. Parse `value` as a decimal, never as a float. | Field | Currency | Meaning | | -------------------- | --------------------- | ----------------------------------------------------------------------------- | | `account_amount` | Account currency | What moved on the account. | | `transaction_amount` | Transaction currency | Original amount, for example a EUR card purchase on a GBP account. | | `base_amount` | Company base currency | For reporting across accounts. | | `fee_amount` | Account currency | Fee charged, negative. Omitted when zero. | | `fx_rate` | — | `transaction_amount ÷ account_amount`, only when currencies differ. | | `running_balance` | Account currency | Posted balance of the account after this transaction. Excludes pending holds. | ## Status lifecycle `pending` moves to exactly one of `completed`, `declined`, or `reversed`, all of which are terminal. Card authorisations start `pending` and become `completed` on settlement. A `completed` transaction that is later refunded appears as a separate `refund` transaction rather than changing status. Subscribe to `transaction.create` and `transaction.update` [webhooks](/guides/webhooks) to be notified of these changes instead of polling. ## Transaction types `direction` is set per transaction by the originating system, so always read it from the transaction rather than inferring it from `type`. | Type | Meaning | | ------------------------------ | ---------------------------------------------------------------------------------------------- | | `card` | Card purchase. | | `atm` | Cash withdrawal. | | `refund` | Card refund. | | `chargeback` | Disputed card transaction returned. | | `out` | Outbound bank payment. | | `in` | Inbound bank payment. | | `direct_debit` | Direct Debit collection. | | `direct_credit` | Inbound credit transfer. | | `direct_credit_return` | Returned inbound credit. | | `recall` | Recalled payment. | | `transfer_out` / `transfer_in` | Transfer between two of the company's own accounts. `related_account_id` holds the other side. | | `exchange_out` / `exchange_in` | Currency exchange between the company's accounts. `related_account_id` holds the other side. | | `fee` | Incard fee. | | `reversal` | Reversal of an earlier transaction. | | `adjustment` | Manual balance adjustment. | | `credit` | Credit applied to the account. | | `loyalty_in` / `loyalty_out` | Reward points converted to or from money. | | `points_in` / `points_out` | Points earned or redeemed. Hidden by default. | | `trophy` | Trophy reward. Hidden by default. | | `referral` | Referral reward. |