# Transactions

The Transactions API returns ledger records created after successful payments are confirmed. Use it to reconcile payments, audit balances, and back up webhook-driven integrations.

## Overview

Each confirmed payment request produces a transaction record. Transactions include gross and net amounts, asset and network metadata, source and destination addresses, and optional on-chain transaction hashes.

Transactions are scoped to the authenticated entity:

- **Account-level API keys** — transactions for that account only
- **Organization-level API keys** — all organization transactions, or a single account when `accountID` is provided

## Authentication

All requests require both headers:

- `Authorization: Bearer <access_token>`
- `x-fluxis-api-key: <your_api_key>`

## List transactions

```
GET /v1/transactions?page=1&page_size=50
```

### Query parameters

| Parameter | Required | Description |
| --------- | -------- | ----------- |
| `page` | Yes | Page number (minimum `1`) |
| `page_size` | Yes | Items per page (`5`–`100`) |
| `accountID` | No | Filter to a specific account (organization keys only). Must belong to your organization |

::::warning
**Swagger drift:** The OpenAPI reference may document `limit` and `offset` query parameters and a flat array response. The live handler uses **`page` and `page_size`** and returns a paginated envelope with `data`, `total`, `page`, `page_size`, and `total_pages`. Follow this page and the handler behavior—not stale swagger types.
::::

### Example

```bash
curl "https://api.fluxis.us/v1/transactions?page=1&page_size=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"
```

For organization keys scoped to one account:

```bash
curl "https://api.fluxis.us/v1/transactions?page=1&page_size=50&accountID=c87464d1-c54a-48c3-80c9-bee4fddf593d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"
```

### Response shape

```json
{
  "data": {
    "data": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "payment_in",
        "status": "completed",
        "gross_amount": "100.00",
        "net_amount": "97.50",
        "expected_amount": "100.00",
        "currency": "USDC",
        "network": "polygon",
        "unique_asset_id": "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "from_type": "wallet",
        "to": "0x1234567890abcdef1234567890abcdef12345678",
        "to_type": "vault",
        "financial_provider": "fluxis",
        "transaction_hash": "0xabcdef...",
        "created_at": "2026-05-21T12:00:00Z",
        "updated_at": "2026-05-21T12:05:00Z"
      }
    ],
    "total": 150,
    "page": 1,
    "page_size": 50,
    "total_pages": 3
  }
}
```

::::note
Optional fields such as `account_external_id`, `unique_asset_id`, `network`, and `transaction_hash` use `omitempty` and may be absent depending on the transaction type and processing stage.
::::

## Transaction types

| Type | Description |
| ---- | ----------- |
| `payment_in` | Inbound customer payment |
| `payment_out` | Outbound payment |
| `deposit` | Deposit |
| `withdraw` | Withdrawal |
| `refund` | Refund |
| `adjustment` | Manual adjustment |
| `swap` | Asset swap |
| `dry_run` | Test / preview record |

Most merchant integrations interact primarily with `payment_in` records created when payment requests reach `confirmed`.

## Transaction statuses

| Status | Description |
| ------ | ----------- |
| `preview` | Preview state |
| `pending` | Awaiting processing |
| `created` | Record created |
| `processing` | In progress |
| `completed` | Successfully completed |
| `failed` | Failed |
| `error` | Error state |
| `expired` | Expired |

## Relationship to payment requests

```mermaid
sequenceDiagram
    participant PR as Payment Request
    participant WH as Webhook
    participant TX as Transaction

    PR->>PR: processing → completed / underpaid / overpaid
    PR->>WH: payment_request_status_update
    PR->>PR: confirmed (ledger step)
    PR->>TX: payment_in transaction created
```

1. Webhooks fire on `processing`, `completed`, `underpaid`, and `overpaid` — see [Webhook Events](/docs/developers/webhook-events).
2. After confirmation, a ledger transaction appears in `GET /v1/transactions`.
3. Poll transactions as a fallback if a webhook is missed.

## Reconciliation pattern

::::note
Combine webhooks (real-time) with periodic transaction polling (safety net). Match on `payment_request_id` via your `external_reference_id` or by correlating amounts, timestamps, and transaction hashes.
::::

Recommended flow:

1. Store payment request IDs when you create checkout sessions
2. Update order state from `payment_request` webhooks
3. Nightly (or on demand), page through `GET /v1/transactions` and reconcile any gaps

## Related documentation

- [Payment Requests](/docs/key-concepts/payment-request) — status lifecycle
- [Webhook Events](/docs/developers/webhook-events) — real-time status updates
- [Webhook Signature Verification](/docs/developers/webhook-signature-verification) — HMAC verification for webhook deliveries
- [Settlements & Consolidation](/docs/key-concepts/settlements-and-consolidation) — how funds move after confirmation
- [API Integration Guide](/docs/developers/tutorials/api-integration-guide) — Step 7 reconciliation