Status & lifecycles

Every resource's status enum, the transitions between states, and which webhook each transition fires.

Every Acute resource has a status enum drawn straight from the typed contract (the TypeScript types you copy into your project). This page is the canonical index: each resource's states, how it moves between them, and the webhook each transition emits. The interactive state machines below let you click a state to see its triggers.

status is the source of truth

Don't infer state from the presence of a timestamp or a webhook arriving. Read status. Events can arrive out of order under retry; the resource's own GET (and the data.status in a webhook) is always authoritative.

A wallet is the account money lives in. From WalletResponseData:

Field	Values
`status`	`active` · `frozen` · `closed`
`kycStatus`	`none` · `tier1`
`kind`	`settlement` · `end_user`

New wallets start active.
frozen suspends money movement (set by you or by Acute); closed is terminal.
kycStatus flips none → tier1 when KYC is submitted, unlocking fund/withdraw/transfer/balance for end-user wallets. (A none wallet attempting those gets WALLET_KYC_REQUIRED.)

activeentry status

The wallet operates normally: it can hold balance, receive, and (once tier-1 KYC'd) send.

Transitions out

activefrozen
Staff freeze the wallet; money movement is blocked, reads continue
activeclosed
The wallet is closed

Reached from

A collection (bank_transfer or virtual_wallet). From PaymentResponseData, status is one of:

pending · partial · settled · expired · failed · refunded · partially_refunded

From	To	Trigger	Webhook
`pending`	`partial`	A partial inbound credit (`0 < amountReceived < payableAmount`); the payment stays open.	none
`pending` / `partial`	`settled`	`amountReceived ≥ payableAmount`; the ledger posting + Acute fee are billed.	`payment.settled`
`pending` / `partial`	`expired`	A `bank_transfer` payment passes its `expiresAt` without full settlement.	`payment.expired`
`pending` / `partial`	`failed`	The collection fails terminally.	none
`settled`	`partially_refunded`	A refund for less than the settled amount completes.	`payment.refunded`
`settled` / `partially_refunded`	`refunded`	A refund brings the refunded total to the full settled amount.	`payment.refunded`

pendingentry status

The virtual account is live and waiting. No money has landed yet; the clock (expiresAt, default +30 min) is ticking.

Transitions out

pendingsettled
An inbound NIP credit reaches payableAmount (overpayment surplus is credited to the wallet too)
firespayment.settled
pendingpartial
An inbound credit arrives but is below payableAmount
firespayment.settled
pendingexpired
The expiry cron fires past expiresAt with nothing (fully) paid
firespayment.expired

A wallet→wallet move. From TransferResponseData, status is:

completed · failed

A transfer is synchronous and terminal on creation: it either posts (completed, emitting transfer.completed) or is rejected (failed). There's no intermediate state: internal transfers don't touch a bank rail.

completedentry statusterminal status

The ledger transaction posted in full: source debited, destination credited, fee remitted. Returned synchronously from the call.

Transitions out

completedcompleted
Posts atomically on a successful POST; there is no pending phase to leave
firestransfer.completed

Reached from

A wallet→bank payout over the NIP rail. From WithdrawalResponseData, status is:

processing · completed · failed · returned

From	To	Trigger	Webhook
(created)	`processing`	The wallet is debited `amount + fees`; the rail transfer is dispatched.	none
`processing`	`completed`	The provider confirms the transfer settled.	`withdrawal.completed`
`processing`	`failed`	The rail rejects the transfer; the async resolver restores the debited funds to the wallet.	`withdrawal.failed`
`processing`	`returned`	The transfer is returned by the beneficiary bank after dispatch; funds are restored.	`withdrawal.failed`

Withdrawals are non-lossy: a failed / returned outcome always restores the money to the source wallet. See Withdrawals.

processingentry status

Funds debited and held in bank_outbound_suspense; the NIP is in flight. The API returns this status; never assume completion from a 201.

Transitions out

processingcompleted
Resolver confirms the NIP via Anchor verifyTransfer
fireswithdrawal.completed
processingreturned
The rail returns the funds; a reversing ledger txn re-credits the wallet
fireswithdrawal.failed
processingfailed
Initiation fails before the transfer leaves; the hold is reversed
fireswithdrawal.failed

A reversal of a settled payment, to bank or wallet. From RefundResponseData, status is:

processing · completed · failed

From	To	Trigger	Webhook
(created)	`processing`	A bank refund is dispatched (a wallet refund posts immediately).	none
`processing`	`completed`	The refund settles (bank rail) or posts (wallet).	`refund.completed`
`processing`	`failed`	A bank refund is rejected/returned by the rail.	`refund.failed`

Wallet-destination refunds complete synchronously; bank refunds resolve asynchronously. See Refunds.

processingentry status

Bank refunds start here: funds held in bank_outbound_suspense while the outbound NIP is in flight. (Wallet refunds skip this entirely.)

Transitions out

processingcompleted
Resolver confirms the bank refund landed via verifyTransfer
firesrefund.completed
processingfailed
The rail fails the refund; the hold is reversed and the wallet re-credited
firesrefund.failed

A batch disbursement from a settlement wallet to many beneficiaries. From PayoutResponseData, the batch status is:

processing · completed · partially_completed · failed

Each item (PayoutItemData) has its own status:

pending · processing · completed · failed

Batch goes to	When	Webhook
`completed`	Every item reached `completed`.	`payout.completed`
`partially_completed`	Some items `completed`, some `failed`.	`payout.partially_completed`
`failed`	The batch failed before any item completed.	none

A payout is created with 202 Accepted and processes items asynchronously; an item's failureReason is populated when it fails. See Payouts.

processingentry status

The batch is running. At least one item is still pending or processing; the rollup stays here until every item resolves.

Transitions out

processingcompleted
All items resolve to completed
firespayout.completed
processingpartially_completed
Items resolve to a mix of completed and failed
firespayout.partially_completed
processingfailed
All items resolve to failed (every hold reversed)

Each webhook delivery (not a resource you create, but worth indexing). From WebhookDeliveryStatus:

pending · success · failed · dead

From	To	Trigger
`pending`	`success`	Your endpoint returned a `2xx`.
`pending`	`failed`	A non-`2xx` / timeout; a retry is scheduled (exponential backoff).
`failed`	`success`	A retry got a `2xx`.
`failed`	`dead`	All 6 attempts exhausted.
`dead`	`pending`	Manual redelivery (console/support) resets and re-queues it.

See Webhook events.

Webhook events

The event each transition above fires, with its full payload.

SDK & types

The exact union types for every status enum on this page.