About the API
A complete reference for the Kadosei API.
Base URL
All API requests are made to the following base URL:
Authentication
The Kadosei API uses two authentication methods depending on the type of request.
JWT
Used for merchant management operations such as creating applications and generating API keys. Obtain a JWT by calling the login endpoint with your merchant credentials. JWTs expire after one hour.
API key
Used for payment operations such as creating sessions and retrieving payment methods. Pass your application API key in the Authorization header.
Authorization: Bearer ks_live_abc123xyz...
API keys are scoped to an application. Each application can have multiple API keys. Keys can be revoked at any time from the merchant portal or via the API.
Request format
All request bodies must be JSON. Set the Content-Type header on every request with a body.
Content-Type: application/json
Responses
Successful responses return a 2xx status code and a JSON body. The structure of each response is documented on the relevant endpoint page.
Errors
Error responses follow a consistent format:
{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}
For validation errors, message may be an array of strings describing each failing field.
Common status codes across all endpoints:
| Status | Meaning |
|---|---|
| 400 | Bad request. The request body or parameters failed validation |
| 401 | Unauthorised. Missing or invalid credentials |
| 403 | Forbidden. Valid credentials but insufficient permissions |
| 404 | Not found. The requested resource does not exist |
| 409 | Conflict. The request conflicts with existing state |
| 422 | Unprocessable. The request is valid but cannot be fulfilled |
| 429 | Too many requests. You have been rate limited |
| 500 | Server error. Something went wrong on our side |
| 502 | Bad gateway. A downstream service returned an error |
| 503 | Service unavailable. Unable to fulfil the request right now |
| 504 | Gateway timeout. A downstream service did not respond in time |
Idempotency
Session creation requests require an Idempotency-Key header containing a client-generated UUID v4. This allows safe retries without creating duplicate sessions. Use a unique key for each new transaction.
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Pagination
Endpoints that return lists support pagination via page and limit query parameters. Responses include the following fields:
| Field | Description |
|---|---|
| page | Current page number (1-based) |
| limit | Number of items per page |
| totalItems | Total number of items available |
| totalPages | Total number of pages |
| hasPreviousPage | Whether a previous page exists |
| hasNextPage | Whether a next page exists |