Utopia Payments API
Accept one-time payments and renewing subscriptions from your own website.
Your server creates a checkout session and redirects the customer to its
checkout_url. They pay on Utopia's secure hosted page, then come back to your
return_url. A signed webhook tells your server the outcome, so you can
fulfil the order even if the customer closes the tab.
| Base URL | https://utopia-payments.com/api/v1 |
| Format | JSON over HTTPS |
| Amounts | Integer minor units: 34900 is AED 349.00 |
| Ids | Prefixed by type: pay_, cks_, sub_, pdt_, cus_, … |
| Spec | OpenAPI 3.1 document |
How a payment works
- Your server calls
POST /checkout_sessionswith what the customer is buying. - You redirect the customer to the session's
checkout_url. - The customer pays on the hosted checkout and returns to your
return_url. - Utopia sends
payment.succeededto your webhook endpoint, and you fulfil the order.
Object ids
Every id is its type's prefix followed by 32 lowercase hexadecimal characters, so you can always tell what one refers to:
| Object | Prefix | Example |
|---|---|---|
| Payment | pay_ | pay_7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d |
| Checkout session | cks_ | cks_9b1e44a0c3d24f6e8a7b5c2d1e0f9a8b |
| Subscription | sub_ | sub_4d8c1a2b3e5f6a7b8c9d0e1f2a3b4c5d |
| Product | pdt_ | pdt_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c |
| Customer | cus_ | cus_2c4e6a8b0d1f4a3c5e7b9d1f3a5c7e9b |
| Webhook endpoint | wh_ | wh_6a1b2c3d4e5f60718293a4b5c6d7e8f9 |
| Event | evt_ | evt_5d0c2b8f1e3a4c6b9d7e8f0a1b2c3d4e |
| API key | key_ | key_8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b |
Store them as strings; nothing else about them is meaningful. An id of the wrong
type, a malformed one, and one belonging to the other mode or another merchant
all answer 404 NOT_FOUND alike — the API never confirms that an id you cannot
reach exists. API keys carry ids too, but you meet them in the dashboard: there
is no keys endpoint in /api/v1.
Start here
Authentication
Create a secret key and make your first request.
One-time payments
Create a checkout session and fulfil orders from the webhook.
Subscriptions
Charge customers automatically every day, week, month or year.
Webhooks
Receive signed events and verify every delivery.
Customers
Create customer records and understand payment-time matching.
Libraries
Node.js, PHP and a WooCommerce plugin.
API reference
Every endpoint, parameter and response, with a request builder.