Paid request lifecycle
Follow an unpaid request, an x402 payment retry, protected work, and its final outcome.
This page follows one payer request. It does not depend on a programming language or SDK.
1. The payer asks for a resource
The payer calls your protected URL. Your application validates ordinary input before it asks Recuut for an access decision. Invalid input must fail before payment is requested.
2. Recuut either allows access or asks for payment
Recuut reads the resource, its published revision, and the active price. If payment is required and the request has no valid payment proof, your application returns HTTP 402 unchanged. The response includes PAYMENT-REQUIRED, which gives an x402-capable payer the information needed to pay and retry.
3. The payer pays and retries
An x402 wallet reads the payment requirements, prepares payment proof, and repeats the same request with PAYMENT-SIGNATURE. The merchant API key stays on your server; it is never sent to the payer or wallet.
4. Your application performs the protected work
When access succeeds, your application performs the work. If the revision requires reporting values, it reports every required value using that revision’s exact names and rules. Streaming protected responses are not supported in v1 because completion must finish before the result is released.
5. Recuut completes the transaction
Your application reports success or failure to Recuut. A successful HTTP 200 completion with status succeeded means the transaction finished. Your application may now return the protected result with PAYMENT-RESPONSE.
An HTTP 202 completion with status settling or reconciling is not success. Keep the result private and check the saved transaction later. If your work fails, report failure; do not claim payment succeeded.
202 exists because settlement can outlive one HTTP request. It means Recuut accepted the completion request but cannot yet prove the terminal payment outcome.
6. The payer receives a final result or a safe pending response
Network interruptions can repeat a request. Make important side effects safe to run more than once when possible. A successful transaction and its receipt are the record that payment completed; a timeout alone is not proof of failure.
| Completion response | Release the result? | Next action |
|---|---|---|
200 + succeeded + PAYMENT-RESPONSE | Yes | Return the protected result and unchanged payment response. |
202 + settling or reconciling | No | Keep the result private and query the transaction by ID. |
200 + failed or any error | No | Return a safe failure and inspect the transaction before retrying side effects. |
Use Get a transaction for a saved ID. Poll with bounded waits; if Retry-After is present, honor it. succeeded and failed are terminal. settling and reconciling are not.