API reference
Every endpoint, parameter and response of the Utopia Payments API.
Each page is generated from the same OpenAPI 3.1 document the server uses, so it always matches the live API. You can also import that document into Postman, Insomnia or an SDK generator.
| Base URL | https://utopia-payments.com/api/v1 |
| Authentication | Authorization: Bearer sk_live_… or sk_test_… (details) |
| Amounts | Integers in minor units |
| Errors | { "code", "message" } with an HTTP status (codes) |
Every endpoint page has a request builder. Requests go straight from your browser to the live API with the key you enter, so use a test key.
Checkout sessions
Start a hosted checkout for a payment or a subscription.
Payments
Look up payments and their status.
Subscriptions
List, inspect and cancel subscriptions.
Products
One-time and recurring prices.
Customers
The people who pay you, and your own metadata on them.
Webhooks
Manage endpoints and signing secrets.
Events
Everything Utopia recorded, delivered or not.
Account
What a key belongs to, and the currencies it may use.
Webhook events
The payload of every event Utopia sends.
WooCommerce
Accept card payments in a WooCommerce store through Utopia's hosted checkout.
Create a checkout session POST
Returns a `checkout_url` to redirect the customer to. A cart with one recurring product starts a subscription; otherwise it takes a one-time payment. Sessions expire after 24 hours. Use it whenever a customer is ready to pay: the card is collected on Utopia's own page, so your server never handles card details. Every item must be in the same currency (`MIXED_CURRENCIES` otherwise), a subscription cart holds that one recurring product and nothing else (`INVALID_CART`), and a saved product must be `active` (`PRODUCT_NOT_ACTIVE`) and priced above zero (`INVALID_PRICE`). List each product once and raise its `quantity` rather than repeating it. Items priced inline are always one-time. An expired session reads as `expired` and has no `checkout_url` left to send anyone to. Send `Idempotency-Key` so a retried request returns the first session instead of creating a second one. A test key sees only test-mode products and creates only test-mode sessions.