# Track and recover a payment

> Understand decisions, human review, settlement, and safe recovery after an uncertain result.

- Human URL: https://conto.finance/docs/guides/payment-lifecycle
- Raw Markdown: https://conto.finance/docs/guides/payment-lifecycle.md
- Terminal view: https://conto.finance/ai/docs/guides/payment-lifecycle

Documentation group: Payments

A payment request is an intent to spend. Authorization permits the next step. It does not prove
funds moved. A transaction records execution. Retain the request ID before executing, then use it
to reconcile the outcome.

## The lifecycle

    Conto approves the payment, sends it for review, or denies it. If it is denied, stop and show
    the reason.

    If a person must review it, keep the request ID. After they decide, read the request status
    again before you continue.

    Once the request is approved, execute it through the managed wallet or send it from your own
    wallet.

    The payment moves to `processing`, then to `completed` or `failed`.

Use `GET /api/sdk/payments/{requestId}` or `conto.payments.status(requestId)` with the same agent
key. Status reads require `transactions:read`. The status endpoint returns lowercase values,
`request` returns uppercase values, and the external-wallet `approve` returns `ready_to_send` when
approved. Do not compare them interchangeably. This table maps each response `status` to the status
read right after it.

| Response `status`   | Returned by                          | Status read                                                       |
| ------------------- | ------------------------------------ | ----------------------------------------------------------------- |
| `APPROVED`          | `request`                            | `approved`                                                        |
| `REQUIRES_APPROVAL` | `request`                            | `review_required`                                                 |
| `DENIED`            | `request`                            | `declined`                                                        |
| `PROCESSING`        | `request` once execution has started | `processing`, `completed`, `failed`, or `reconciliation_required` |
| `ready_to_send`     | `approve` (external wallet)          | `approved`                                                        |
| `review_required`   | `approve` (external wallet)          | `review_required`                                                 |
| `declined`          | `approve` (external wallet)          | `declined`                                                        |

What each status read means:

| Status read               | Meaning                                                           | What your application does                                                   |
| ------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `approved`                | Authorization permits the next payment step                       | Check expiry and your stored execution state before sending                  |
| `review_required`         | Waiting for a human decision                                      | Retain the ID and wait for an authorized reviewer                            |
| `reconciliation_required` | The transfer may have been sent and Conto must review the outcome | Retain the request and transaction IDs, and investigate before another write |
| `processing`              | Execution or reconciliation is in progress                        | Poll with a deadline or consume webhooks. Do not send again                  |
| `completed`               | The payment flow completed                                        | Inspect the transaction and the original execution receipt                   |
| `declined`                | Controls or review stopped the request                            | Explain the result. Do not execute                                           |
| `failed`                  | The payment flow failed                                           | Reconcile transaction evidence before deciding on a new intent               |
| `expired`                 | Authorization expired                                             | Do not execute this authorization. Decide whether a new request is needed    |

## What proves settlement?

Execution returns `receipt.transactionId` and `receipt.settlementMode`. `live` means an onchain
transfer, including testnet. `test` means simulated settlement, with no transaction hash, explorer
URL, block number, or confirmation time. Status and transaction reads repeat `settlementMode`.
`unknown` means Conto has no execution evidence for the request. `completed` alone does not prove
funds moved onchain. Preserve the receipt and request ID.

For an onchain flow, wait for `transaction.status: "completed"` and check the intended chain.
A hash alone, an approval, or HTTP 200 is not confirmation.

## Bounded polling

Call this helper after submission or an uncertain result. It only reads state. Any state other
than `processing`, including review, expiry, and denial, returns control to your application. Also
configure the SDK request timeout: an in-flight HTTP call can finish after the polling deadline.

```typescript

export async function waitForPayment(
  conto: Pick
,
  requestId: string,
  timeoutMs = 60_000
): Promise
 {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const state = await conto.payments.status(requestId);
    if (state.status !== 'processing') return state;
    await new Promise((resolve) => setTimeout(resolve, 2_000));
  }
  throw new Error(`Still processing: retain ${requestId} and check again later`);
}
```

If a read fails with 429, honor `Retry-After` and resume later with the same request ID. A polling
deadline or read failure does not cancel the payment. See [rate limits](https://conto.finance/docs/guides/rate-limits).

## Recovery recipes

### Execution timed out

1. Read the original request ID. A timeout is not proof that execution failed.
2. If there is a transaction, follow that transaction to completion or failure.
3. If the state is unresolved, retain it and investigate. Do not automatically repeat execution,
   even if the authorization still reads `approved`.
4. Create a new intent only after establishing the original outcome and confirming the business
   action still needs payment. Preserve the association between both intents.

A repeated execute never sends twice. After completion it returns the existing receipt with
`alreadyExecuted: true`. While another attempt is in flight, it returns `409 PAYMENT_PROCESSING`.
Reconcile the original request before any other write.

Durably persist your business action ID, idempotency key, Conto request ID, execution attempt, and
receipt so a restarted worker can discover an earlier execution attempt.

### A human must approve

Keep `REQUIRES_APPROVAL` requests pending in your application. An authorized reviewer decides in
the configured [approval workflow](https://conto.finance/docs/guides/approval-workflows). For a managed wallet, approving the
payment in Conto executes it. Check the same request ID after review: `payments.status()` shows the
transaction, and `payments.execute()` returns the existing receipt with `alreadyExecuted: true`
instead of sending again. Before approval, `execute()` returns `409 APPROVAL_PENDING`. A declined
payment returns `403 PAYMENT_DENIED` with `reasons`.

### External confirmation returns a conflict

Send through your external signer only after approval. Confirm using the request ID, final hash,
and the approval token when one was issued. After human workflow approval, the token can be omitted.

Repeated confirmation does not duplicate recorded spend but can return `409 ALREADY_CONFIRMED`.
Compare the returned `txHash` with your saved transfer and follow `statusUrl`. If the hashes differ,
stop and investigate. Never send a second transfer to resolve a confirmation error.

### The wallet has insufficient funds

Inspect the intended wallet's address, network, currency, and available balance. Funding another
wallet or chain does not repair this request. After funding, re-read the request and check expiry
and prior execution evidence before you resume or request new authorization.

### A webhook is missing or repeated

Reconcile with the payment status endpoint. Verify webhook signatures and persist accepted events
before returning success. Handle duplicate or out-of-order delivery without creating a new payment.
Let the current resource state decide your next action. Follow
[webhook delivery and deduplication](https://conto.finance/docs/guides/webhooks).

## Next steps

Use [server integration examples](https://conto.finance/docs/quickstart/connecting-agents#server-handlers) to connect recovery to an authenticated
application route, and exercise these paths with [payment tests](https://conto.finance/docs/guides/policy-testing).
