API Reference
The complete machine-readable contract is published as OpenAPI 3.1:
Import it into Postman, Insomnia, Stoplight or generate a client with openapi-generator. A test in the Cartino Pay suite fails whenever a route exists that is missing from the spec, so the document cannot drift from the implementation.
Interactive explorer
The explorer below is rendered from the same openapi.yaml (Swagger UI, loaded from a CDN; if you are offline use the raw file).
Endpoint summary
Base URL: https://pay.cartino.net — all endpoints require Authorization: Bearer <token> and speak JSON.
| Method | Path | Purpose |
|---|---|---|
GET |
/api/v1/me |
Identify the calling application |
POST |
/api/v1/payments |
Create a payment (supports Idempotency-Key) |
GET |
/api/v1/payments |
List payments (order_id, status, from, to, per_page, page) |
GET |
/api/v1/payments/{payment_id} |
Get a payment |
POST |
/api/v1/payments/{payment_id}/verify |
Verify with the gateway (idempotent) |
Inbound to your application:
| Method | Path | Purpose |
|---|---|---|
GET |
your callback URL ?payment_id=&order_id=&status= |
Payer's browser returns |
POST |
your webhook URL | Signed outcome event |
Versioning
All endpoints live under /api/v1. Backwards-compatible additions (new optional fields, new statuses announced in advance, new endpoints) happen within v1. Breaking changes ship as /api/v2 alongside v1 with a deprecation period. Unversioned paths are never exposed.
Conventions
- Timestamps are ISO-8601 with offset (
2026-09-14T10:05:10+03:30). - Amounts are integers in Rials.
- IDs:
payment_id=PAY_+ 26 uppercase alphanumerics;event_id= UUID. - Pagination:
meta.current_page,meta.last_page,meta.per_page,meta.total.