Checkout.com Python SDK

Getting started

Requirements

• Python 3.10 or higher
• pip

Installation

pip install checkout-sdk

For a specific version:

pip install checkout-sdk==<version>

Version 3.0.0 is here!

We improved the initialization of SDK making it easier to understand the available options.
Now NAS accounts are the default instance for the SDK and ABC structure was moved to a previous prefixes.
If you have been using this SDK before, you may find the following important changes:

• Imports: if you used to import checkout_sdk.payments.payments now use checkout_sdk.payments.payments_previous
• Marketplace module was moved to Accounts module, same for classes and references.
• In most cases, IDE can help you determine from where to import, but if you’re still having issues don't hesitate to open a ticket.

🚀 Please check in GitHub releases for all the versions available.

📖 Checkout our official documentation.

• Official Docs (Default)
• Official Docs (Previous)

📚 Check out our official API documentation guide, where you can also find more usage examples.

• API Reference (Default)
• API Reference (Previous)

How to use the SDK

This SDK can be used with two different pair of API keys provided by Checkout. However, using different API keys imply using specific API features. Please find in the table below the types of keys that can be used within this SDK.

Note: sandbox keys have a sbox_ or test_ identifier, for Default and Previous accounts respectively.

If you don't have your own API keys, you can sign up for a test account here.

PLEASE NEVER SHARE OR PUBLISH YOUR CHECKOUT CREDENTIALS.

Subdomain value

Requests must be made through your merchant-specific subdomain (MSSD): the first 8 characters of your client ID (excluding cli_). For example, if your client ID is cli_vkuhvk4vjn2edkps7dfsq6emqm, your subdomain is vkuhvk4v. When environment_subdomain is set the SDK sends requests to https://vkuhvk4v.api.checkout.com. Private Link merchants use their pl- prefixed subdomain (for example pl-vkuhvk4v), which the SDK also accepts. See Base URLs and API endpoints for further details, and for where to find your unique client ID.

Default

Default keys client instantiation can be done as follows:

from checkout_sdk.checkout_sdk import CheckoutSdk
from checkout_sdk.environment import Environment


def default():
    # public key is optional, only required for operations related with tokens
    checkout_api = CheckoutSdk
        .builder()
        .secret_key('secret_key')
        .public_key('public_key') # optional, only required for operations related with tokens
        .environment(Environment.sandbox()) # or production()
        .environment_subdomain("subdomain") # required, Merchant-specific DNS name, the first 8 characters of your client ID
        .build()

    payments_client = checkout_api.payments
    payments_client.refund_payment('payment_id')

Default OAuth

The SDK supports client credentials OAuth, when initialized as follows:

from checkout_sdk.checkout_sdk import CheckoutSdk
from checkout_sdk.environment import Environment
from checkout_sdk.oauth_scopes import OAuthScopes


def oauth():
    checkout_api = CheckoutSdk
        .builder()
        .oauth()
        .client_credentials(client_id='client_id', client_secret='client_secret')
        .environment(Environment.sandbox()) # or production()
        .environment_subdomain("subdomain") # required, Merchant-specific DNS name, the first 8 characters of your client ID
        .scopes([OAuthScopes.GATEWAY_PAYMENT_REFUNDS, OAuthScopes.FILES]) # optional, array of scopes
        .build()

    payments_client = checkout_api.payments
    payments_client.refund_payment('payment_id')

Previous

If your pair of keys matches the Previous type, this is how the SDK should be used:

from checkout_sdk.checkout_sdk import CheckoutSdk
from checkout_sdk.environment import Environment

def previous():
    # public key is optional, only required for operations related with tokens
    checkout_api = CheckoutSdk
        .builder()
        .previous()
        .secret_key('secret_key')
        .public_key('public_key') # optional, only required for operations related with tokens
        .environment(Environment.sandbox()) # or production()
        .environment_subdomain("subdomain") # optional for the Previous platform, Merchant-specific DNS name
        .build()

    payments_client = checkout_api.payments
    payments_client.refund_payment('payment_id')

Logging

Checkout SDK custom logger can be enabled and configured through Python's logging module:

import logging
logging.basicConfig()
logging.getLogger('checkout').setLevel(logging.INFO)

HttpClient

Checkout SDK uses requests library to perform http operations, and you can provide your own custom http client implementing HttpClientBuilderInterface

import requests
from requests import Session

import checkout_sdk
from checkout_sdk.checkout_sdk import CheckoutSdk
from checkout_sdk.environment import Environment
from checkout_sdk.oauth_scopes import OAuthScopes
from checkout_sdk.http_client_interface import HttpClientBuilderInterface


class CustomHttpClientBuilder(HttpClientBuilderInterface):

    def get_client(self) -> Session:
        session = requests.Session()
        session.max_redirects = 5
        return session


def oauth():
    checkout_api = CheckoutSdk
        .builder()
        .oauth()
        .client_credentials(client_id='client_id', client_secret='client_secret')
        .environment(Environment.sandbox()) # or production()
        .environment_subdomain("subdomain") # required, Merchant-specific DNS name, the first 8 characters of your client ID
        .http_client_builder(CustomHttpClientBuilder()) # optional
        .scopes([OAuthScopes.GATEWAY_PAYMENT_REFUNDS, OAuthScopes.FILES]) # optional, array of scopes
        .build()

    payments_client = checkout_api.payments
    payments_client.refund_payment('payment_id')

Exception handling

All the API responses that do not fall in the 2** status codes will cause a CheckoutApiException. The exception encapsulates the http_metadata, request_id, error_type, and a list of error_details, if available.

try:
    checkout_api.customers.get("customer_id")
except CheckoutApiException as err:
    http_status_code = err.http_metadata.status_code
    request_id = err.request_id
    error_type = err.error_type
    error_details = err.error_details

Building from source

Prerequisites

• Python 3.10 or higher
• pip (latest version)

Setup Development Environment

1. Clone the repository

   git clone https://github.com/checkout/checkout-sdk-python.git
   cd checkout-sdk-python
   

2. Create and activate virtual environment

   python3.10 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies

   pip install --upgrade pip
   pip install -r requirements-dev.txt
   

4. Install pre-commit hooks (optional but recommended)

   pre-commit install
   

Running Tests

# Run all tests
python -m pytest --import-mode=append --runxfail tests/

# Run specific test file
python -m pytest tests/payments/payments_client_test.py -v

# Run with coverage
python -m pytest --cov=checkout_sdk tests/

Code Quality

The project uses flake8 and pylint for code quality checks:

# Run flake8
flake8 checkout_sdk tests --count --max-complexity=10 --max-line-length=127 --statistics

# Run pylint
pylint checkout_sdk

If you installed pre-commit hooks, these checks will run automatically before each commit.

Environment Variables

The execution of integration tests require the following environment variables set in your system:

• For Default account systems: CHECKOUT_DEFAULT_PUBLIC_KEY & CHECKOUT_DEFAULT_SECRET_KEY
• For OAuth account systems: CHECKOUT_DEFAULT_OAUTH_CLIENT_ID & CHECKOUT_DEFAULT_OAUTH_CLIENT_SECRET
• For Previous account systems: CHECKOUT_PREVIOUS_PUBLIC_KEY & CHECKOUT_PREVIOUS_SECRET_KEY
• Processing channel: CHECKOUT_PROCESSING_CHANNEL_ID

Legacy domain (emergency use only)

⚠️ Only use if merchant specific sub domains are causing issues. Connecting through your merchant-specific subdomain (see Subdomain value) is the supported way of using the Checkout.com API, and non-subdomain usage will be deprecated.

If, in exceptional circumstances, you cannot use your merchant-specific subdomain, you can explicitly opt out by calling use_legacy_domain() instead of environment_subdomain(...):

checkout_api = CheckoutSdk.builder() \
    .secret_key("secret_key") \
    .environment(Environment.sandbox()) \
    .use_legacy_domain() \
    .build()

This routes requests to api.checkout.com (or api.sandbox.checkout.com) and access.checkout.com (or access.sandbox.checkout.com). The method raises a DeprecationWarning, so python -W error::DeprecationWarning and most linters will flag it. Exactly one of environment_subdomain(...) or use_legacy_domain() must be set: the SDK raises a CheckoutArgumentException if both, or neither, are. The Previous (ABC) platform predates merchant-specific subdomains and is exempt from this requirement.

Code of Conduct

Please refer to Code of Conduct

Licensing

MIT