API reference
The machine-readable contract is the OpenAPI 3.1 document — the source of truth for the API.
A rendered, interactive reference is coming with the developer portal (Phase 3). Until then, this is the endpoint overview and the raw spec above.
Phase 1 endpoints
Base URL https://payxiro.com/api/v1. All endpoints authenticate with a bearer secret key; the sk_test_ / sk_live_ prefix selects the environment.
| Method | Path | Description |
|---|---|---|
| GET | /ping | Liveness / auth check |
| POST | /customers | Create a Customer (dedupes on external_ref) |
| GET | /customers | List Customers (cursor pagination) |
| GET | /customers/{id} | Retrieve a Customer |
| POST | /payments | Create a Payment (requires Idempotency-Key) |
| GET | /payments | List Payments |
| GET | /payments/{id} | Retrieve a Payment |
| POST | /payments/{id}/submit-form | Submit manual-method dynamic-form values |
| POST | /checkout_sessions | Create a hosted Checkout Session (requires Idempotency-Key) |
| GET | /checkout_sessions/{id} | Retrieve a Checkout Session |
| POST | /webhook_endpoints | Register a Webhook Endpoint (secret shown once) |
| GET | /webhook_endpoints | List Webhook Endpoints |
| GET | /webhook_endpoints/{id} | Retrieve a Webhook Endpoint |
| PATCH | /webhook_endpoints/{id} | Update a Webhook Endpoint |
| DELETE | /webhook_endpoints/{id} | Delete a Webhook Endpoint |
Conventions recap
- Amounts are decimal strings; asset codes are CODE or CODE.NETWORK; timestamps are ISO-8601 UTC.
- List endpoints use cursor pagination:
limit(default 20, max 100) andstarting_after; responses carryhas_moreandnext_cursor. No page numbers, no total counts. - Filter on the standard indexed columns:
status(comma-separated),asset_code,country,customer,provider_account,created_after/created_before. - Errors use the
{ "error": { type, code, message, param, request_id } }envelope. - v1 evolves additively only — tolerate unknown fields and enum values on read.
Not yet live
Payouts, Refunds, Wallets, and the Events log are specified in the API design but are not exposed in Phase 1 (crypto-first, deposits-only — ADR-0012). They ship additively when built: Payouts in Phase 2+, Refunds later. The OpenAPI document describes only what the running server exposes today, so the spec never drifts from reality.
See Getting started for auth, idempotency, and the error envelope in full.