API Reference

The PaymentKit API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Base URL

All API requests should be made to:

https://api.paymentkit.com/api

For example, to list customers: https://api.paymentkit.com/api/customers

Authentication

The PaymentKit API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Authentication is performed via HTTP Bearer token. Include your secret token in the Authorization header:

$
curl https://api.paymentkit.com/api/customers \
>
  -H "Authorization: Bearer st_prod_your_secret_token"

PaymentKit provides two types of tokens:

Your secret tokens carry many privileges, so keep them secure. Do not share them in publicly accessible areas such as GitHub, client-side code, or browser requests.

Request format

Send request data as JSON with the Content-Type: application/json header:

$
curl https://api.paymentkit.com/api/customers \
>
  -H "Authorization: Bearer st_prod_your_secret_token" \
>
  -H "Content-Type: application/json" \
>
  -d '{"email": "customer@example.com", "name": "Jane Smith"}'

Errors

PaymentKit uses conventional HTTP response codes to indicate the success or failure of an API request.

Error responses include a JSON body with details:

1
{
2
  "type": "about:blank",
3
  "title": "Bad Request",
4
  "status": 400,
5
  "detail": "Customer email is required",
6
  "instance": "/api/customers",
7
  "request_id": "req_abc123"
8
}

The request_id can be used when contacting support to help diagnose issues.

Pagination

List endpoints return paginated results. Use limit and offset query parameters:

$
curl "https://api.paymentkit.com/api/customers?limit=20&offset=0" \
>
  -H "Authorization: Bearer st_prod_your_secret_token"

Paginated responses include metadata:

1
{
2
  "items": [...],
3
  "total": 150,
4
  "has_more": true
5
}

Expanding responses

Some endpoints support expanding related data. Use the expand query parameter:

$
curl "https://api.paymentkit.com/api/customers/cus_prod_abc123?expand=custom_fields" \
>
  -H "Authorization: Bearer st_prod_your_secret_token"

Available expansions vary by endpoint. Common expansions include custom_fields for entities that support custom field values.

IDs

All objects have a unique identifier prefixed with the object type and environment:

The environment segment is prod for production or stg for staging.