Settlement failures

A rejected request moved no money and returns an error code you fix. A settlement that started and did not finish is held, in full, and reported by name on the payment.

Where	What you get	Who acts
Before anything exists	An error code on your request	You
After settlement started	An operational state on the payment	Stableyard, usually

Fix these error codes in your request

Code	HTTP	Meaning	What to do
`settlement_profile_required`	422	Returned by `POST /v2/payments` when the receiving account has no settlement profile, or its profile no longer resolves to an active destination backed by an active wallet	Check the account’s destinations rather than assuming nothing was set. Set a profile, then replay the create with the same idempotency key
`settlement_not_ready`	409	Settlement has not reached the state this operation needs. Typically a refund arriving after merchant settlement or fee payout has begun	Read the payment. If settlement has started, a partner-created refund is no longer the route, and the return is handled as a recovery
`settlement_already_exists`	409	A settlement operation for that payment is already created, signing, broadcast or under review	Do not create a second one. Read the payment and wait for the first to resolve
`payment_method_not_supported`	422	The chosen destination cannot receive settlement	Select a crypto destination with `capabilities.settlementSupported: true`

Stableyard refuses to create a receiving object it cannot deliver from, rather than holding the money. Settlement destinations covers listing and setting a destination, and Errors lists every code with its HTTP status.

A destination change never re-routes money

Situation	What happens
The preferred destination is disabled	The disable is refused. Select a different active destination first
A bank or rail destination is selected	Refused. It returns `settlementSupported: false` with an `unavailableReason` such as `linked_bank_receive_settlement_not_enabled` or `bank_settlement_provider_not_configured`
The destination changes after a payment was created	Nothing re-routes. Every payment and every detected deposit snapshots the destination in force when it was created

That last row is the safety property: a settings change cannot redirect money already on its way.

A payout that fails after funding recovers to the frozen crypto destination

For an outbound leg, offrampStatus distinguishes a failure that cost nothing from one that did.

`offrampStatus`	What it means
`not_started`	Funding was never confirmed. Nothing was collected and no recovery applies
`failed`	A verified terminal payout failure after confirmed funding
`refunding`	A recovery is reserved against the sending account’s frozen preferred crypto settlement destination
`refunded`	That recovery settled and is confirmed

A failure before funding is confirmed is not a failed payout. Create a new payment with a fresh quote; do not raise it as a recovery.

A recovery settles to the preferred crypto destination frozen at the moment it is reserved. If the sending account has no active preferred crypto destination, no recovery starts and it waits for a person. Keeping one on every paying account is your obligation, not a default.

`requires_intervention` goes to a person

operationalState is a separate axis from status: a payment can be accepted and healthy, or accepted and stopped. Which of these states you can meet depends on the capabilities switched on for your app.

`operationalState`	`operationalReasonCode`	What it means
`retrying`	`settlement_retry_scheduled`	Automation is still working. No action
`requires_intervention`	`settlement_unconfirmed`	Settlement was submitted and confirmation has not arrived
`requires_intervention`	`settlement_failed`	Settlement to the destination failed
`requires_intervention`	`settlement_requires_intervention`	Automation stopped for review

Deposits carry the same idea: status: requires_intervention on the deposit, and settlement.status: requires_intervention with a reasonCode naming why. Raw provider errors are never exposed there. Financial status is preserved through all of this. An accepted or succeeded payment does not regress because an operational field changed; if your records can move an order backwards out of a fulfilled state on an operational event, the model is wrong.

You do	A person does
Fix a missing or invalid settlement destination, then replay	Resolve any `requires_intervention` state
Read the payment instead of retrying blindly	Decide what happens to funds held after a failure
Put a held payment in a queue in front of a named operator	Release a settlement stuck unconfirmed
Keep a preferred crypto destination on every paying account	Reserve and confirm a post-funding recovery

Never create a replacement payment to work around a stuck one. Reuse the original payment and its idempotency key. A second payment for the same obligation is how a recipient gets paid twice.

Next: Settlement webhooks and testing

The events to act on, and the cases to rehearse in sandbox.

Start here

Settling

Operating it

Fix these error codes in your request

A destination change never re-routes money

A payout that fails after funding recovers to the frozen crypto destination

`requires_intervention` goes to a person

Next: Settlement webhooks and testing

​Fix these error codes in your request

​A destination change never re-routes money

​A payout that fails after funding recovers to the frozen crypto destination

​requires_intervention goes to a person

Next: Settlement webhooks and testing

Fix these error codes in your request

A destination change never re-routes money

A payout that fails after funding recovers to the frozen crypto destination

`requires_intervention` goes to a person