Core concepts
Payment intents
Payment intents are the core collection resource. You create an intent, share checkout details, then consume lifecycle updates.
Lifecycle
Payment intents are the core collection resource. You create an intent, share checkout details, then consume lifecycle updates.
requires_paymentCreated. Awaiting payer deposit.
→processingOn-chain deposit progress.
→completedFunds credited. Webhook fired.
→expiredTTL elapsed; not settled.
→failedPermanent failure; see error fields.
Create an intent
curl $XPEND_BASE/v1/payment-intents \
-H "Authorization: Bearer $XPEND_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_8421" \
-d '{
"amount": "150.00",
"chain": "ethereum",
"token": "USDC",
"metadata": { "order_id": "order_8421" }
}'Required payload keys
| Key | Type | Description |
|---|---|---|
| amount | string (decimal) | Amount in base units for selected asset. |
| chain | enum | Network identifier (e.g. ethereum, base, polygon). |
| token | enum | Token symbol on that chain (USDC, USDT). |
Optional payload keys, enums, and defaults
| Key | Type | Description |
|---|---|---|
| metadata | object | Default: {}. Merchant-defined non-financial metadata echoed in responses/webhooks. |
| funding_mode | enum | Optional override. Rejected when it conflicts with merchant type policy. |
| reference | string | Your order/invoice ID. Echoed everywhere for reconciliation. |
Funding acceptance mode rules
Each merchant has a default funding-mode policy. Per-request overrides are accepted as long as they don't conflict with that policy.
Important response fields
id, payment intent ID, persist in your order record.checkout_url, hosted checkout URL when available.deposit_address, fallback for API-first flows.merchant metadata, echoed from creation.status, merchant-visible lifecycle state.
Read / list intents
GET /v1/payment-intents with cursor pagination and filters on status, reference, and date range.
Recommended integration pattern
One key per business action
Persist the returned payment intent ID in your order record. Consume webhook events for status transitions. Polling aggressively is unnecessary, use webhooks for state transitions and occasional reads for UI refresh.
Don't poll the same intent every second
Payment intents are the core collection resource. You create an intent, share checkout details, then consume lifecycle updates from webhooks.