Checkout.com Authentication: API Keys & Secure Processing

Authentication overview

Checkout.com secures interactions with its API through a set of distinct authentication methods primarily centered around API keys. These keys serve as credentials to verify the identity of an application or user making requests to the Checkout.com platform. Proper authentication is critical for maintaining the security and integrity of payment transactions, protecting both merchant and customer data. The system distinguishes between keys used for server-side operations and those for client-side interactions, ensuring that sensitive operations are always handled with the highest level of security.

The Checkout.com API is designed around REST principles, utilizing standard HTTP methods and JSON payloads. Authentication credentials must be included with each API request to process transactions, retrieve data, or manage account settings successfully. The platform adheres to security standards such as PCI DSS Level 1, which mandates strict controls around handling cardholder data, making robust authentication a foundational component of its service offering.

Supported authentication methods

Checkout.com employs different types of API keys, each with specific use cases and permissions, to facilitate secure access and operations. The primary methods involve using secret keys for server-to-server communication and public keys for client-side interactions, often in conjunction with tokenization. Webhooks also utilize a distinct secret for signature verification.

API Keys

API keys are alphanumeric strings that uniquely identify and authenticate a requesting application or user. Checkout.com primarily uses two types of API keys:

• Secret Key (or Secret API Key): This key grants full access to your Checkout.com account and should be kept strictly confidential. It is used for server-side operations, such as creating charges, capturing payments, issuing refunds, and managing subscriptions. All requests made with the secret key must originate from a secure server environment.
• Public Key (or Public API Key): This key is designed for client-side use, typically within web browsers or mobile applications. Its primary function is to securely tokenize sensitive payment information (e.g., credit card numbers) before it reaches your server. The public key does not grant direct access to sensitive API operations but allows for the secure collection of payment details without them ever touching your backend, thereby reducing your PCI DSS compliance burden.

Webhook Signature Verification

Webhooks are used by Checkout.com to notify your application of events occurring on their platform (e.g., payment successful, refund issued). To ensure the authenticity and integrity of these notifications, Checkout.com sends a signature with each webhook request. Your application must verify this signature using a shared secret (the Webhook Secret) configured in your Checkout.com Hub. This process confirms that the webhook payload originated from Checkout.com and has not been tampered with in transit. Checkout.com's webhook documentation provides details on implementing this verification.

Summary of Authentication Methods

Getting your credentials

All authentication credentials for Checkout.com are managed within the Checkout.com Hub, your merchant portal. Here's a general guide to obtaining your keys:

1. Access the Hub: Log in to your Checkout.com Hub account. If you don't have an account, you will need to sign up and complete the onboarding process.
2. Navigate to API Keys: Typically, API keys are located under sections like "Developer Settings," "API Keys," or "Settings > Channels." The exact path may vary slightly based on updates to the Hub interface. Refer to the Checkout.com API Keys documentation for the most current instructions.
3. Generate or Retrieve Keys: You will find your existing Public Key and options to generate or view your Secret Key. For security reasons, Secret Keys are often shown only once upon generation, or require a re-generation if lost. Always store your Secret Key securely.
4. Set up Webhook Secret: In the webhook configuration section, you can define and retrieve your Webhook Secret. This secret is crucial for verifying incoming webhook payloads from Checkout.com to your application.
5. Environment Management: Checkout.com provides separate environments for testing (Sandbox) and live transactions (Production). Ensure you are generating and using the correct keys for the environment you intend to work with. Sandbox keys will not work in production, and vice-versa.

Authenticated request example

When making API requests to Checkout.com, the Secret API Key is typically passed in the Authorization header using the Bearer token scheme. For client-side tokenization, the Public API Key is used within the Checkout.js library or SDKs.

Example using a Secret API Key (server-side payment creation)

This cURL example demonstrates how to create a payment using your Secret API Key. Replace sk_test_YOUR_SECRET_KEY with your actual Secret API Key and adjust the request body as needed.

curl -X POST "https://api.checkout.com/payments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -d '{"source":{"type":"token","token":"tok_xxxxxxxxxxxxxxxxxxxxxx"},"amount":1000,"currency":"GBP","reference":"ORDER-1234","metadata":{"udf1":"test"}}'

For operations involving dynamic data or more complex logic, using one of Checkout.com's official SDKs (e.g., Python SDK, Java SDK) is recommended. These SDKs handle the underlying HTTP requests and authentication headers, simplifying integration and reducing the chance of errors.

Example using a Public API Key (client-side tokenization with JavaScript)

This conceptual JavaScript example shows how a Public API Key is used with Checkout.js to tokenize card details. This process happens in the customer's browser, preventing sensitive card data from ever reaching your server directly.

import { Checkout } from '@checkout/checkout-sdk-js';

const checkout = new Checkout('pk_test_YOUR_PUBLIC_KEY', {
  environment: 'sandbox',
});

async function tokenizeCard(cardDetails) {
  try {
    const tokenResponse = await checkout.tokens.request({ card: cardDetails });
    console.log('Token generated:', tokenResponse.token);
    // Send this token to your backend for payment processing using your Secret Key
    return tokenResponse.token;
  } catch (error) {
    console.error('Tokenization error:', error);
    throw error;
  }
}

// Example usage with dummy card details
// tokenizeCard({
//   number: '4242...', // Customer's actual card number
//   expiryMonth: '12',
//   expiryYear: '2026',
//   cvv: '123'
// });

This client-side approach, often referred to as direct tokenization, helps merchants reduce their PCI DSS scope significantly, as they do not directly handle raw card data.

Security best practices

Implementing robust security measures is crucial when integrating with any payment gateway. Adhering to these best practices will help protect your systems and your customers' sensitive information when using Checkout.com:

• Keep Secret API Keys Confidential: Your Secret API Key grants administrative access to your Checkout.com account. Never expose it in client-side code, public repositories, or send it directly from a web browser. Store it securely in environment variables or a secrets management service on your server.
• Use Environment-Specific Keys: Always use separate API keys for your development/sandbox and production environments. This prevents accidental live transactions during testing and limits the impact if a non-production key is compromised.
• Rotate API Keys Regularly: Periodically rotate your Secret API Keys, typically every 90-180 days, or immediately if there is any suspicion of compromise. The Checkout.com Hub allows you to generate new keys and deactivate old ones.
• Implement Webhook Signature Verification: Always verify the signature of incoming webhooks to ensure they originate from Checkout.com and have not been tampered with. This protects against malicious actors attempting to send fraudulent event notifications to your system.
• Filter and Validate Webhook Events: Only process webhook events relevant to your application and validate their content. Do not implicitly trust the data received in a webhook until it has been verified and validated against your business logic.
• Principle of Least Privilege: If Checkout.com supports role-based access control or scoped API keys (check their documentation), use them to grant only the necessary permissions to each application or user. This minimizes the potential damage if a key is compromised.
• Secure Your Servers: Ensure that the servers making API calls with your Secret API Key are hardened and regularly patched. Employ firewalls, intrusion detection systems, and monitor access logs.
• Use HTTPS Everywhere: All communication with Checkout.com, both from your client-side applications and your servers, must occur over HTTPS (TLS 1.2 or higher) to encrypt data in transit and prevent eavesdropping.
• PCI DSS Compliance: Understand your responsibilities under PCI DSS. While Checkout.com is PCI DSS Level 1 compliant, your integration methods (especially if not using client-side tokenization) can impact your own compliance requirements.
• Error Handling and Logging: Implement robust error handling for API calls. Log authentication failures and other security-related events for auditing and incident response, but ensure that sensitive information like API keys is never logged.