---
updatedAt: 2026-02-28T11:25:20.000Z
agentTools:
  projectIndex: https://neutronpay.readme.io/llms.txt
---

# 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](/reference/confirmtransaction). 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](mailto:support@neutron.me).      |
| `usercanceled` | Cancelled by the user via [Cancel endpoint](/reference/canceltransaction). |

## 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](/reference/purpose) and receive state change notifications automatically.

**Polling**: Call [Get Transaction](/reference/gettransactionstatus) periodically. Check `txnState` in the response.

```bash
# 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.

## Related

* [Create Transaction](/reference/createtransaction) — Start a new transaction
* [Confirm Transaction](/reference/confirmtransaction) — Confirm a quoted transaction
* [Get Transaction](/reference/gettransactionstatus) — Check transaction status
* [Cancel Transaction](/reference/canceltransaction) — Cancel before confirmation
* [Webhook Guide](/reference/purpose) — Real-time state change notifications