This page covers the patterns and conventions that apply across all Infinia APIs. Reading it before you start will save you time later.

Resources are async

All Infinia APIs are async-first. When you create a resource — a payment, a payout, an internal transfer — the API returns immediately with an initial state (typically PENDING or IN_PROGRESS). The final outcome arrives later via webhook.

Every resource follows the same lifecycle:

Create — POST to the relevant endpoint. You get back the resource in its initial state.
Poll — GET the resource by ID if you need to check its current state on demand.
Webhook — Infinia POSTs the updated resource to your callback URL when its state changes.

📘
The object returned by the create endpoint, the get endpoint, and the webhook payload all share the same schema. You can reuse the same parsing and validation logic across all three.

Use webhooks, not polling

The right way to track state changes is webhooks. They're near-real-time, automatically retried on failure, and scale without any extra effort on your side.

Polling the retrieve endpoint is fine as a fallback — for example, to reconcile state after a webhook delivery failure or a temporary outage on your side — but it should not be your primary approach.

See the Webhooks page for setup instructions, signature verification, and retry behaviour.

Idempotency

Operations that move money — payouts, internal transfers, and similar — require a unique identifier in the request body (the field name varies by endpoint, e.g. origin_id, idempotency_key). This value acts as an idempotency key.

If you submit the same key twice, the API returns the result of the first request instead of executing the operation again. This makes it safe to retry after a timeout or a 5xx error without risking a duplicate transaction.

The recommended pattern:

Generate a unique identifier for each operation and persist it on your side before sending the request
If the request fails due to a network error or 5xx, retry with the same identifier
Do not retry on 4xx errors — those indicate a problem with the request itself

⚠️
Idempotency protects against duplicate execution, not against bad inputs. A request that fails with a 400 will return the same 400 if retried with the same key.

Pagination

List endpoints use cursor-based pagination. Pass limit (max 100) to control page size, and pass the next_cursor from each response to fetch the next page. When has_more is false, you've reached the end.

Keep your filters consistent across all pages of a session — changing a filter mid-session will invalidate the cursor.

See the Pagination page for a full example.

Questions or feedback

If you run into something unexpected or have suggestions, reach out at devs@infiniaweb.com.