Transaction Status Types

Every Neutron transaction moves through a series of states from creation to completion. This page documents all possible states, their meaning, and how they flow together.

State Flow Diagram

Typical Happy Path

quoted → userconfirmed → srccreated → srcconfirmfilled → destsent → completed

Full State Diagram

                    ┌─────────────┐
                    │   quoted    │  Transaction created
                    └──────┬──────┘
                           │
                ┌──────────┼──────────┐
                │          │          │
                ▼          ▼          ▼
          ┌──────────┐ ┌────────┐ ┌───────────────┐
          │ expired  │ │canceled│ │ userconfirmed  │
          │ (final)  │ │(final) │ │                │
          └──────────┘ └────────┘ └───────┬────────┘
                                          │
                                          ▼
                                   ┌─────────────┐
                                   │  srccreated  │  Source side created
                                   └──────┬───────┘
                                          │
                                   ┌──────┴───────┐
                                   │              │
                                   ▼              ▼
                           ┌────────────┐  ┌───────────────────┐
                           │  srcsent   │  │ srcpendconfirmfill │
                           └─────┬──────┘  └────────┬──────────┘
                                 │                  │
                                 ▼                  ▼
                         ┌───────────────┐  ┌─────────────────┐
                         │  srcintent    │  │ srcconfirmfilled │
                         └───────────────┘  └────────┬────────┘
                                                     │
                                              ┌──────┴──────┐
                                              │             │
                                              ▼             ▼
                                      ┌─────────────┐ ┌──────────┐
                                      │ destpendsent│ │  failed   │
                                      └──────┬──────┘ │ (final)   │
                                             │        └──────────┘
                                             ▼
                                      ┌─────────────┐
                                      │   destsent   │  Payout sent
                                      └──────┬───────┘
                                             │
                                      ┌──────┴──────┐
                                      │             │
                                      ▼             ▼
                              ┌───────────┐  ┌──────────┐
                              │ completed │  │ rejected │
                              │  (final)  │  │ (final)  │
                              └───────────┘  └──────────┘

                              ┌──────────┐
                              │  error   │  Can occur at any non-final state
                              │ (final)  │
                              └──────────┘

All States

Creation & Confirmation

State	Description	Final?
`quoted`	Transaction created. Awaiting user confirmation, or will expire after a timeout.	No
`userconfirmed`	User confirmed via Confirm endpoint. Processing begins.	No
`expired`	Transaction expired — not confirmed or funded in time.	✅ Yes

Source (Pay-In) States

These track the incoming side of the transaction — the funds coming in.

State	Description	Final?
`srccreated`	Source request created (e.g., Lightning invoice generated, on-chain address watching).	No
`srcsent`	Deposit or invoice request has been sent to the network.	No
`srcintent`	Source payment intent detected (e.g., on-chain transaction seen but unconfirmed).	No
`srcpendconfirmfill`	Payment received, pending final confirmation (e.g., waiting for on-chain confirmations).	No
`srcconfirmfilled`	Source payment fully confirmed. Funds received.	No

Destination (Pay-Out) States

These track the outgoing side — the funds being delivered.

State	Description	Final?
`destpendsent`	Payout queued, pending send.	No
`destsent`	Payout sent to the destination (e.g., Lightning payment in flight, on-chain TX broadcast).	No

Final States

State	Description
`completed`	Transaction fully settled — both sides done. ✅
`expired`	Timed out before confirmation or funding.
`rejected`	Rejected by the system (e.g., compliance, invalid destination).
`error`	Non-recoverable error — contact support.
`usercanceled`	Cancelled by the user via Cancel endpoint.

Typical Flows by Method

Lightning (instant)

quoted → userconfirmed → srccreated → srcconfirmfilled → completed

Lightning payments skip the destsent state — settlement is atomic.

On-Chain Bitcoin

quoted → userconfirmed → srccreated → srcintent → srcpendconfirmfill → srcconfirmfilled → destsent → completed

On-chain requires multiple confirmation steps.

Internal Swap

quoted → userconfirmed → completed

Wallet-to-wallet swaps settle immediately.

Fiat Payout

quoted → userconfirmed → srccreated → srcconfirmfilled → destpendsent → destsent → completed

Fiat payouts include a destpendsent queuing step.

Handling States in Your Integration

Which states to watch for

Goal	Watch for
Payment received	`srcconfirmfilled` or `completed`
Payment sent	`destsent` or `completed`
Something went wrong	`failed`, `rejected`, `error`
User didn't act in time	`expired`

Webhooks vs Polling

Webhooks (recommended): Register a webhook and receive state change notifications automatically.

Polling: Call Get Transaction periodically. Check txnState in the response.

# Poll transaction status
curl https://api.neutron.me/api/v2/transaction/YOUR_TXN_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Idempotency

Your system may receive the same state notification multiple times (via webhook retries). Always check if you've already processed a state change before taking action.

Create Transaction — Start a new transaction
Confirm Transaction — Confirm a quoted transaction
Get Transaction — Check transaction status
Cancel Transaction — Cancel before confirmation
Webhook Guide — Real-time state change notifications