Authentication
Every request to the Paytab API is authenticated with an API key sent as a Bearer token. Requests without a valid key return 401 Unauthorized.
Publishable keys
Prefixed pk_test_ / pk_live_. Safe to embed in browser and mobile clients. Can tokenise payment details and confirm PaymentIntents only.
Secret keys
Prefixed sk_test_ / sk_live_. Server-only. Grant full access to your account — never commit them or ship them to the browser.
Sending a request
Send your secret key in the Authorization header using the Bearer scheme.
curl https://api.paytab.co.uk/v1/balance \
-H "Authorization: Bearer sk_test_51H...abc" \
-H "Paytab-Version: 2026-06-01"Test mode vs live mode
Test keys hit a sandbox that is byte-for-byte identical to production. No real cards, no real money — same webhook payloads, same error codes, same latency profile.
Idempotency
Send an Idempotency-Key header on any POST. Retrying with the same key within 24 hours returns the original response — safe to retry through network failures.
Idempotency-Key: 9f4b2a1e-...-payment-42Versioning
Pin an API version with the Paytab-Version header. Without it we use the version active when your account was created — your integration never breaks silently.
Restricted keys
Create scoped keys with read-only or per-resource permissions from Developers → API keys. Ideal for analytics jobs, dashboards and CI.
If a key leaks
Rotate immediately from the dashboard. The old key remains valid for 24 hours so you can roll deploys — after that it returns 401.
Error responses
Auth failures always return a machine-readable JSON error.
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API key provided.",
"doc_url": "https://paytab.co.uk/developers/authentication"
}
}