"
```
The envelope itself is validated at the route layer — `x402Version`, `scheme`, and `network` are checked against the link's accepted set. The inner `payload` is scheme-specific (EIP-3009 fields for `exact` on EVM) and is carried opaquely to the facilitator.
A successful retry returns `200 X402SettlementResponse`:
```json theme={null}
{
"success": true,
"transaction": "0xababab...",
"network": "eip155:1329",
"payer": "0xcdcdcd...",
"receipt_url": "/v0/payment-links/public/q79Rx34K...",
"_links": {
"self": { "href": "/pay/q79Rx34K..." },
"canonical": { "href": "/v0/payment-links/public/q79Rx34K..." }
}
}
```
A retry against a link that has already been settled returns `409 PAYMENT_LINK_ALREADY_SETTLED` regardless of envelope validity — the check sits above the signature branch. **The signature does not reopen a closed link.**
05 / LIFECYCLE AND EXPIRY
## Pending. Settled. Expired.
A payment link has three lifecycle states. `settled` and `expired` are terminal.
```mermaid theme={null}
stateDiagram-v2
[*] --> pending : POST /v0/payment-links
pending --> settled : x402 settlement succeeds
pending --> expired : effective expiry passes
settled --> [*]
expired --> [*]
```
| State | Meaning | Fields populated |
| --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------ |
| `pending` | Issued, unsettled, and inside the effective expiry window. | Creation fields only. |
| `settled` | A payer successfully redeemed the link. | `settled_at`, `tx_hash`, `settle_chain_id`, `payer_addr`, `usage_count`. |
| `expired` | The effective expiry passed before settlement. Terminal. | Creation fields only. |
**Effective expiry is the stricter of `payment_link.expires_at` and the underlying `pint.expires_at`.** Both are persisted as epoch milliseconds — the API normalises the PINT's seconds-valued EIP-712 input on the server. Whichever deadline comes first closes the window for both the public view and the agent pay route.
Once a link is `settled`, further retries return `409 PAYMENT_LINK_ALREADY_SETTLED`. The public view continues to render — `settled_at`, `tx_hash`, and `payer_addr` are now populated and serve as a permanent receipt. **A settled link is a permanent record, not a deleted one.**
06 / ERRORS
## RFC 7807, everywhere.
Every error is returned as [RFC 7807 Problem Details](/error-handling) with a stable `error_code`. The ones a partner will encounter most:
| Status | Error code | When you hit it |
| ------ | --------------------------------------- | -------------------------------------------------------------------- |
| 400 | `GENERAL_VALIDATION_ERROR` | Malformed slug, invalid or inverted date range on list. |
| 400 | `PAYMENT_LINK_X402_INVALID_PAYLOAD` | `PAYMENT-SIGNATURE` envelope was not parseable. |
| 400 | `PAYMENT_LINK_X402_VERSION_MISMATCH` | Envelope `x402Version` is not `2`. |
| 400 | `PAYMENT_LINK_X402_UNSUPPORTED_SCHEME` | Envelope scheme is not `exact`. |
| 400 | `PAYMENT_LINK_X402_UNSUPPORTED_NETWORK` | Envelope network is not in the link's `accepted_chains`. |
| 401 | — | Missing or invalid JWT on an owner-scoped route. |
| 403 | — | User-status gate rejected the caller (account not yet at `pending`). |
| 404 | `PAYMENT_LINK_NOT_FOUND` | Slug does not exist, or exists but is owned by another user. |
| 409 | `PAYMENT_LINK_SLUG_CONFLICT` | Slug collision on create — retry the request. |
| 409 | `PAYMENT_LINK_ALREADY_SETTLED` | Retry against a link whose `transaction_id` is populated. |
| 410 | `PAYMENT_LINK_EXPIRED` | Effective expiry has passed. |
| 422 | — | Request body failed schema validation. |
| 424 | — | Upstream PINT issuance failed during link creation. |
| 429 | — | 60-per-minute per-IP rate limit on public endpoints. |
The `instance` field on each error points to the route that emitted it; the `trace_id` field ties it to your Logfire span for support. **One format, one code space — read the code and act.**
07 / SEE ALSO
## Related.
The concept page — why the URL and the 402 carry the same signature, and what the verifier checks.
The signed primitive underneath every payment link. Mint flow, scopes, and EIP-712 shape.
The verifier-side flow — what a merchant does when a payer presents a PINT JWT.
Full RFC 7807 reference and the stable error-code catalogue.
## Reference
### Supported chains
At private-alpha launch, **Sei is the settlement network**. Base, Optimism, and Tempo follow shortly after. The `accepted_chains` field stays enum-typed across the roster — code against the enum and new networks surface without an API change.
| Chain ID | Network | Alpha status |
| -------- | ----------- | --------------------------------- |
| 1329 | Sei | Launch chain |
| 1328 | Sei Testnet | Available for integration testing |
| 8453 | Base | Coming soon |
| 10 | Optimism | Coming soon |
| — | Tempo | Coming soon |
### Lifecycle statuses
| Value | Terminal? |
| --------- | --------- |
| `pending` | No |
| `settled` | Yes |
| `expired` | Yes |
### x402 schemes
| Value | Supported today |
| ------- | --------------- |
| `exact` | Yes |
## Questions.
No. The slug is the signature bytes, url-safe base64-encoded — signing the same intent twice produces the same slug, and the second create call returns `409 PAYMENT_LINK_SLUG_CONFLICT` rather than issuing a duplicate. This is intended: one signed intent, one link.
The link accepts settlements until its effective expiry. Most integrations want `max_uses: 1` — it is the safer default for invoice-style flows.
The owner view mirrors the create response — it is the authoritative object, including `pint_uri` and `usage_count` useful for reconciliation. The public view adds the full EIP-712 message, signature, and nonce so a payer wallet can verify locally before settling. Neither view exposes anything that would compromise the link.
Sei at launch. Base, Optimism, and Tempo follow shortly after. The Sei testnet (`1328`) is available for integration testing. The `accepted_chains` field stays enum-typed across the roster — code against the enum and new networks surface without an API change.