Copy page

Platform

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

Code
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

Example

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

Code
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

Code
{
  "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
  }
}

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

Code
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.
2. After confirmation, a ledger transaction appears in GET /v1/transactions.
3. Poll transactions as a fallback if a webhook is missed.

Reconciliation pattern

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 — status lifecycle
• Webhook Events — real-time status updates
• Webhook Signature Verification — HMAC verification for webhook deliveries
• Settlements & Consolidation — how funds move after confirmation
• API Integration Guide — Step 7 reconciliation