Verification and settlement
The difference between authorization, verification and settlement, and exactly when a payment counts as successful.
On this page
Three stages
- Authorization
- The payer signs a transfer for the quote. Nothing has moved: the transaction lacks the fee payer's signature, so it can't land on-chain by itself.
- Verification
- NODRA checks the signed transfer against the quote and its rules, and simulates it on Solana. A verified payment is reserved for one call. Still nothing has moved.
- Settlement
- After a billable answer, NODRA co-signs and submits the transfer, and Solana confirms it. Now the money is in the API's vault.
When a payment is successful
A 200 answer alone doesn't mean the payment settled: if confirmation takes more than 5 seconds, you get the answer with success: false and errorReason: "settlement_pending", and settlement continues.
Serve first
NODRA calls the provider before it submits the payment. This is why a failed or unbillable call costs nothing: the transfer simply isn't submitted. NODRA doesn't take the payment first and refund later, and it has no refunds.
A payment the provider has answered but that hasn't been submitted (for example after a crash) is recovered within about 30 seconds: NODRA retries settlement while the payer's transaction is still valid (its blockhash lasts about 60 to 90 seconds). After that, it's recorded as settlement failed, a served call that is never paid.
Duplicate protection
- One payment per quote. A second, different transaction for a used quote is rejected with
quote_already_used. - One use per signed payment. NODRA stores a hash of each payment's transaction message under a unique constraint, so the same payment can't be accepted twice, even across restarts or gateway instances. Resending it returns
409. - One upstream call per payment. Only one request can claim a reserved payment; a concurrent duplicate gets
409 payment_in_progress.
Exposure limit
Because NODRA serves before it settles, it limits how much each paying wallet can have in flight: unsettled payments per wallet are capped (1 USDC in the current configuration). A payment over the cap is rejected with exposure_cap_exceeded until earlier ones settle.