Transactions

Transactions are served by the Incard transactions service through the Developer Gateway under /developer/transactions. Every request needs Authorization: Bearer <access_token> and X-On-Behalf-Of: <company_id> — see 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

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):

{
  "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.
`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": "<message>" }.

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:

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

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": "<decimal string>", "currency": "<ISO 4217>" } 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 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.

Get started

Resources

Events

Endpoints

List transactions

What the list includes by default

Filters

Enrichment

Get a transaction

Amounts and signs

Status lifecycle

Transaction types

​Endpoints

​List transactions

​What the list includes by default

​Filters

​Pagination

​Enrichment

​Get a transaction

​Amounts and signs

​Status lifecycle

​Transaction types

Endpoints

List transactions

What the list includes by default

Filters

Pagination

Enrichment

Get a transaction

Amounts and signs

Status lifecycle

Transaction types