> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle and status codes

> Payment, deposit and refund states, the separate operational axis, and which values are terminal.

A payment carries two independent state fields. Reading only one is the most common source of integration bugs.

| Field | Answers |
| - | - |
| `status` | Did money move, and what was the result |
| `operationalState` | Does this need retrying or a human |

A payment can be `processing` and `normal`, or `processing` and `requires_intervention`. The first is healthy. The second is not, and nothing about `status` tells you so.

## Payment status

| Status | Meaning | Terminal |
| - | - | - |
| `requires_payment_method` | Created; the payer has not chosen how to pay | No |
| `requires_action` | Something must happen before it can proceed, usually by the payer | No |
| `processing` | Funds are moving or being verified | No |
| `accepted` | Funds were received and verified, settlement is not finished | No |
| `succeeded` | Complete. Value reached the destination | **Yes** |
| `failed` | Did not complete | **Yes** |
| `cancelled` | Cancelled before completion | **Yes** |
| `expired` | The window closed before funds arrived | **Yes** |

<Warning>
  `accepted` is not `succeeded`. Funds are verified as received, but settlement to the destination has not completed. Fulfil an order on `succeeded` unless you have deliberately decided that verified receipt is enough for your product.
</Warning>

`intent` is `receive` or `send`, and does not change after creation.

## Operational state

| State | Meaning |
| - | - |
| `normal` | Nothing unusual |
| `retrying` | An automatic retry is scheduled. No action needed |
| `requires_intervention` | Automation has stopped. A human decision is needed |

When `operationalState` is not `normal`, `operationalReasonCode` names the cause. The ones worth handling in your own operations tooling:

| Reason code | What happened |
| - | - |
| `duplicate_payment_detected` | A second payment arrived for the same obligation |
| `late_payment_received` | Funds arrived after the window closed |
| `collection_requires_intervention` | Collection could not complete automatically |
| `payout_failed`, `payout_requires_intervention` | The outbound leg failed |
| `settlement_failed`, `settlement_requires_intervention` | Settlement to the destination failed |
| `settlement_unconfirmed` | Settlement was submitted but is not confirmed |
| `refund_failed`, `refund_requires_intervention` | A refund could not complete |
| `fee_payout_failed`, `fee_payout_requires_intervention` | Fee movement failed |
| `custody_after_failure` | Funds are held following a failure |

Codes ending `_retry_scheduled` are informational. Automation is still working.

## Deposit status

For funds arriving at a reusable deposit address.

| Status | Meaning | Terminal |
| - | - | - |
| `detected` | Seen on chain, not yet confirmed | No |
| `confirming` | Waiting for the required confirmations | No |
| `settling` | Moving to the account's settlement destination | No |
| `settled` | Delivered to the destination. Credit here | No. It can still become `reversed` |
| `reversed` | Stableyard invalidated the settled accounting record. This does not imply an on-chain clawback | **Yes** |
| `failed` | Did not complete | **Yes** |
| `ignored` | Recorded and not credited, typically below the asset's minimum | No. It can be re-evaluated |
| `requires_intervention` | A person must decide | No |

## Deposit address status

`active` or `disabled`. A disabled address stops being monitored for new deposits; deposits already in flight continue.

## Reading state correctly

<Steps>
  <Step title="A webhook is a prompt">
    It tells you something changed. It does not tell you what is true now, and events can arrive out of order or more than once.
  </Step>

  <Step title="Read the resource">
    `GET /v2/payments/{paymentId}` is the answer. Act on what it returns, not on the event body.
  </Step>

  <Step title="Check both axes">
    A terminal `status` with `operationalState: requires_intervention` still needs attention.
  </Step>

  <Step title="Treat terminal as final">
    A terminal status does not reopen. Late evidence changes operational state, not the financial result.
  </Step>
</Steps>

## Next

<CardGroup cols={2}>
  <Card title="Webhooks" icon="bell" href="/webhooks">
    Events, delivery and signature verification.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/errors">
    Why a request was rejected before any state existed.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.