Skip to main content
Every funding intent is in exactly one state. States fall into three groups, and the grouping is the useful part: it tells you whether to wait, to stop, or to do something.

​
The states

These progress on their own. Wait for a webhook.

​
Two distinctions worth internalising

payment_received is not settling. The user’s obligation ends and our work begins at different moments. Release the user from your checkout at payment_received; do not hold them until settled. settled means the ledger credit exists. Not that a transaction hash appeared. If you are deciding whether to grant a user something, settled is the only state that answers the question.

​
Underpayment

Crypto payers underpay routinely, most often because a sending exchange deducts its fee from the amount. You configure what happens:
Overpayment needs no policy. The intent settles for the required amount and the excess is refunded automatically.

​
Refunds

Refunds are a first-class operation, not a support process. Automatic on expiry with funds received, on execution failure, on overpayment, and on compliance rejection. You can also initiate one with POST /funding_intents/{id}/refunds from payment_received, partially_settled, undeliverable, or failed.
On rails where the payer is not reliably refundable, an exchange withdrawal being the common case, our checkout collects a refund endpoint before accepting payment. If you build your own checkout, collect one too, or you will accumulate intents in refund_failed.
Refunds are always compensating ledger entries. Nothing is ever reversed in place, so the audit trail stays intact.