Authentication

The Checkout Page API uses API key authentication with Bearer tokens. All API requests must include a valid API key in the authorization header.

API key format

All requests to the Checkout Page API must include an authorization header with your API key in the following format:

Authorization: Bearer YOUR_API_KEY

Getting your API key

1. Sign up for Checkout Page: Create an account at checkoutpage.com
2. Access your dashboard: Navigate to your seller dashboard
3. Generate API key: Go to Settings > API Keys and generate a new API key
4. Copy your key: Securely store your API key - it won't be shown again

Making authenticated requests

cURL example

curl -X GET https://api.checkoutpage.com/v1/customers \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json"

JavaScript example

const apiKey = process.env.CHECKOUTPAGE_API_KEY;

const response = await fetch('https://api.checkoutpage.com/v1/customers', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

Python example

import os
import requests

api_key = os.environ.get('CHECKOUTPAGE_API_KEY')
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.checkoutpage.com/v1/customers',
    headers=headers,
)

data = response.json()

Authentication errors

If authentication fails, you'll receive the following response.

HTTP Status: 401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key"
}

Test mode

Purchases made while a page is in test mode create test records with livemode: false. Payments, bookings, subscriptions, subscription payments, invoices, submissions and tickets all work this way.

Reading test data

A live key (sk_live_) reads live records by default. To read test records with it, add livemode=false to the list and get endpoints for those records:

curl "https://api.checkoutpage.com/v1/payments?livemode=false" \
  -H "Authorization: Bearer sk_live_1234567890abcdef"

Without livemode=false, a live key leaves test records out, so fetching a test record by its id returns 404.

Keys that start with sk_test_ can only read test data: livemode=true returns 403 with the message Test API keys can only read test data. Remove livemode=true or use a live API key.

Writes

Write endpoints don't take livemode. Creating a booking, cancelling a subscription and regenerating an invoice use the mode of your API key, so a live key creates and changes live records. Validating a ticket finds the ticket by its id, whatever its mode, and updating a ticket works on live tickets.

Best practices

Environment variables

Store your API key as an environment variable:

# .env file
CHECKOUTPAGE_API_KEY=sk_live_1234567890abcdef

Error handling

Always handle authentication errors gracefully:

async function makeApiRequest() {
  try {
    const response = await fetch('https://api.checkoutpage.com/v1/endpoint', {
      headers: {
        Authorization: `Bearer ${process.env.CHECKOUTPAGE_API_KEY}`,
      },
    });

    if (!response.ok) {
      if (response.status === 401) {
        throw new Error('Authentication failed - check your API key');
      }
      throw new Error(`API request failed: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('API request error:', error.message);
    throw error;
  }
}

Security considerations

• Never log API keys: Ensure API keys are not logged in your application
• Use HTTPS only: All API requests must use HTTPS
• Rotate keys regularly: Generate new API keys periodically and revoke old ones
• Limit key access: Only give API access to systems that need it

Next steps

Now that you understand authentication, explore these API capabilities: