Authentication
Every API request identifies your application with a bearer token:
Authorization: Bearer cp_live_Ab3dEf6hIj9kLm2nOp5qRs8tUv1wXy4zAb7cDe0fGh3iJk6lMn9o
Token types
| Prefix | Mode | Gateways it can use |
|---|---|---|
cp_live_ |
Live | Any enabled gateway (sandbox or live) |
cp_test_ |
Test | Sandbox gateways only — a test token can never reach a live merchant account. Payments created with it are flagged "test": true. |
An application can hold several active tokens (for example one per environment, or an old and a new one during rotation). Admins can revoke any token instantly.
Rules
- Tokens are shown once when issued. Cartino Pay stores only a SHA-256 hash.
- Never embed tokens in front-end code, mobile apps or URLs. Call Cartino Pay from your server.
- Store the token in your secret manager / environment variables, not in the repository.
- If a token leaks, ask an admin to revoke it and issue a new one. Use the multi-token feature to rotate without downtime: issue the new token, deploy, then revoke the old one.
Failure responses
| HTTP | error.code |
Meaning |
|---|---|---|
| 401 | UNAUTHENTICATED |
Header missing |
| 401 | INVALID_TOKEN |
Unknown, revoked or expired token |
| 403 | APPLICATION_DISABLED |
Your application was disabled by an admin |
| 429 | RATE_LIMITED |
Too many requests (see below) |
Failed authentication attempts are logged (with the token prefix only) and throttled per IP.
Rate limiting
Each application has a per-minute request budget (default 120, configurable per application). Responses include:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
When exceeded you receive 429 RATE_LIMITED with error.details.retry_after seconds.
Verifying your credentials
curl https://pay.cartino.net/api/v1/me -H "Authorization: Bearer cp_live_…"
Returns your application slug, status, default gateway (and whether it is sandbox or live), registered callback URLs, webhook URL and token mode — everything you need to debug a misconfiguration, and nothing secret.