Track and recover a payment

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

Use GET /api/sdk/payments/{requestId} or conto.payments.status(requestId) with the same agent key. Status reads require transactions:read. The status endpoint uses lowercase values; authorization responses use uppercase values. Do not compare the two interchangeably.

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
`action_required`	Another customer action is needed	Present `action.url`, then check this request again
`reconciliation_required`	Execution evidence needs reconciliation	Retain the request and transaction IDs; 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. New test receipts omit transaction hashes and explorer URLs. Preserve the receipt and request ID. Status and transaction endpoints repeat settlementMode; unknown means execution evidence is absent or the legacy record cannot establish the mode. Never infer onchain settlement from completed or a legacy hash alone. A simulated record has no blockchain confirmation time or block number. 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. For a sandbox flow, a completed test receipt demonstrates the API workflow without a blockchain transfer.

Bounded polling

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

import { Conto, type PaymentStatusResult } from '@conto_finance/sdk';

export async function waitForPayment(
  conto: Pick<Conto, 'payments'>,
  requestId: string,
  timeoutMs = 60_000
): Promise<PaymentStatusResult> {
  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; resume later with the same request ID. A polling deadline or read failure does not cancel the payment. See rate limits.

Recovery recipes

Execution timed out

Read the original request ID. A timeout is not proof that execution failed.
If there is a transaction, follow that transaction to completion or failure.
If the state is unresolved, retain it and investigate; do not automatically repeat execution even if the authorization still reads approved.
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 can return 400 INVALID_STATUS after completion or 409 ALREADY_EXECUTED for an execution conflict. Reconcile the original request in either case. Persist your business action ID, idempotency key, Conto request ID, execution attempt, and receipt durably. A restarted worker must be able to 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. Check the same request ID after review: an approved decision is not a settlement receipt, and the workflow may already have begun execution. Only perform a next write when its state and your stored attempt history permit it.

The SDK throws ACTION_REQUIRED

HTTP 402 rejects the SDK promise. Catch ContoError, preserve error.requestId, and present error.actionUrl. After the customer finishes, read the original request instead of creating another payment. See the request example.

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 deciding whether to resume or request new authorization.

A webhook is missing or repeated

Use the payment status endpoint to reconcile. Verify webhook signatures and persist accepted events before returning success. Handle duplicate or out-of-order delivery without creating a new payment; the current resource state should determine your application’s next action. Follow webhook delivery and deduplication.

Next steps

Use server integration examples to connect recovery to an authenticated application route, and exercise these paths with payment tests.

Get started

Payments

Spending controls

Integrations

Production

Conto Pay

Track and recover a payment

The lifecycle

What proves settlement?

Bounded polling

Recovery recipes

Execution timed out

A human must approve

The SDK throws ACTION_REQUIRED

External confirmation returns a conflict

The wallet has insufficient funds

A webhook is missing or repeated

Next steps

​The lifecycle

​What proves settlement?

​Bounded polling

​Recovery recipes

​Execution timed out

​A human must approve

​The SDK throws ACTION_REQUIRED

​External confirmation returns a conflict

​The wallet has insufficient funds

​A webhook is missing or repeated

​Next steps

The lifecycle

What proves settlement?

Bounded polling

Recovery recipes

Execution timed out

A human must approve

The SDK throws ACTION_REQUIRED

External confirmation returns a conflict

The wallet has insufficient funds

A webhook is missing or repeated

Next steps