Checkout.com Getting Started: Account, Keys, First Request

Getting started overview

Integrating with Checkout.com begins with establishing an account, securing API credentials, and making an initial API call to verify connectivity. This process enables developers to configure payment processing capabilities, fraud detection, and other financial services offered by the platform. The objective is to move from initial setup to a functional test transaction within a sandbox environment, preparing for a live deployment.

The following table summarizes the key steps:

Create an account and get keys

To begin using Checkout.com, developers must first create an account. This account provides access to the Checkout.com Hub, a dashboard where critical administrative tasks, reporting, and API key management are performed. The signup process typically involves providing business details and agreeing to terms of service.

1. Sign Up for a Test Account: Navigate to the Checkout.com Get Started page and follow the prompts to create a new account. It is recommended to start with a test account to explore features without impacting live transactions.
2. Access the Hub: Once registered, log in to the Checkout.com Hub. This interface is central to managing your integration.
3. Locate API Keys: Within the Hub, go to the 'Developer' section, then 'API Keys'. Here you will find your essential credentials:
   • Secret Key: Used for authenticating server-side API requests. This key should be kept confidential and never exposed in client-side code. It typically begins with sk_.
   • Public Key: Used for client-side operations, such as tokenizing card details directly from a customer's browser. This key can be exposed in client-side code. It typically begins with pk_.
   • Webhook Secret: Used to verify the authenticity of webhooks received from Checkout.com, ensuring they originate from the platform.

For security, API keys should be handled according to best practices, such as storing secret keys in environment variables or secure vault services rather than directly in code repositories. The OAuth 2.0 framework, which Checkout.com supports for certain integrations, provides a secure method for delegated authorization without sharing direct credentials, as described in the OAuth 2.0 specification.

Your first request

The goal of your first request is to confirm that your API keys are correctly configured and that you can successfully interact with the Checkout.com sandbox environment. A common first request involves creating a payment. This example uses cURL, but similar logic applies to Checkout.com's SDKs for JavaScript, PHP, Java, Python, .NET, and Ruby.

Prerequisites

• Your Secret Key (sk_...).
• The Checkout.com sandbox API base URL: https://api.sandbox.checkout.com.
• A test card number from the Checkout.com test cards documentation.

Step-by-step Request

1. Create a Payment Source (Tokenization):

   Before creating a payment, you'll typically tokenize the card details. This process converts sensitive card information into a secure, single-use token that can be safely passed to your server. For a server-side test, you can simulate this by directly providing card details, but for a real-world client-side integration, you would use the Public Key and Checkout.js or an SDK.

   Example cURL to create a payment source token (for testing purposes, directly providing card details):

   curl -X POST "https://api.sandbox.checkout.com/tokens"
     -H "Authorization: sk_test_YOUR_SECRET_KEY"
     -H "Content-Type: application/json"
     -d '{
       "type": "card",
       "number": "4242424242424242",
       "expiry_month": "12",
       "expiry_year": "2030",
       "cvv": "123"
     }'

   The response will contain a token value (e.g., tok_xxxxxxxxxxxxxxxxxxxx). Copy this token.

2. Create a Payment:

   Use the token obtained in the previous step to create a payment. This request should be made from your server, using your Secret Key.

   curl -X POST "https://api.sandbox.checkout.com/payments"
     -H "Authorization: sk_test_YOUR_SECRET_KEY"
     -H "Content-Type: application/json"
     -d '{
       "source": {
         "type": "token",
         "token": "tok_xxxxxxxxxxxxxxxxxxxx" 
       },
       "amount": 1000, 
       "currency": "USD",
       "reference": "ORDER-12345",
       "capture": true,
       "customer": {
         "email": "[email protected]"
       }
     }'

   Replace tok_xxxxxxxxxxxxxxxxxxxx with the token you received. The amount is in the smallest currency unit (e.g., 1000 for $10.00 USD).

3. Verify the Response:

   A successful payment creation will return a 201 Created HTTP status code and a JSON body containing details of the payment, including a status field (e.g., Captured or Authorized) and a unique id for the payment. You can also verify the transaction in the Checkout.com Hub under the 'Transactions' section.

Common next steps

Once you've successfully made your first API call, you can proceed with further integration and testing:

• Explore Webhooks: Configure webhooks to receive real-time notifications about payment status changes (e.g., successful capture, refunds, disputes). This is crucial for building robust payment workflows. Refer to the Checkout.com webhooks documentation for setup instructions.
• Implement SDKs: Utilize one of the provided Checkout.com SDKs to simplify API interactions in your preferred programming language. SDKs handle authentication, request formatting, and response parsing, reducing development effort.
• Integrate Client-Side Card Tokenization: For secure handling of card details directly from the browser, integrate Checkout.js or the client-side components of an SDK. This ensures PCI DSS compliance by preventing sensitive card data from ever hitting your servers, as outlined in PCI DSS requirements.
• Handle Different Payment Methods: Expand your integration to support various payment methods beyond basic card payments, such as Apple Pay, Google Pay, local payment methods, or alternative payment methods. The Checkout.com payment methods guide provides details.
• Implement Fraud Detection: Integrate Checkout.com's fraud detection tools to minimize risk. This often involves sending additional customer and transaction data with payment requests.
• Go Live: When testing is complete, switch to your live API keys and production endpoints. This transition typically requires verification from Checkout.com and adherence to their go-live checklist.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some troubleshooting tips:

• Check API Key: Ensure you are using the correct Secret Key (sk_test_... for sandbox) in the Authorization header. A common mistake is using the Public Key or a live key in the sandbox environment.
• Verify Endpoint: Confirm that you are sending requests to the correct sandbox URL (https://api.sandbox.checkout.com). Using the live endpoint with test keys will result in authentication errors.
• Content-Type Header: The Content-Type: application/json header is mandatory for most POST requests. Missing or incorrect headers will lead to parsing errors.
• Request Body Format: Ensure your JSON request body is correctly formatted and includes all required fields as per the Checkout.com API reference. Typos or missing commas can cause JSON parsing failures.
• Test Card Details: Use valid test card numbers and expiry dates provided by Checkout.com. Using real card details in the sandbox or invalid test details will cause transactions to fail. Refer to the Checkout.com test cards documentation.
• Error Messages: Carefully read the error messages returned in the API response. Checkout.com's API provides descriptive error codes and messages that can pinpoint the exact problem. For example, a 401 Unauthorized typically indicates an API key issue, while a 422 Unprocessable Entity suggests issues with the request body data.
• Hub Logs: Check the transaction logs in your Checkout.com Hub. Failed transactions often have detailed error information recorded there, which can aid in diagnosis.
• Network Issues: Verify that your network firewall or proxy is not blocking outbound requests to the Checkout.com API endpoints.