3. Set environment variables (choose one auth method):

# Option A: Static API keys
CKO_SECRET_KEY=sk_sbox_xxxxxxxx
CKO_PUBLIC_KEY=pk_sbox_xxxxxxxx

# Option B: OAuth credentials
CKO_SECRET=your_api_secret
CKO_CLIENT=ack_xxxxxxxx
CKO_SCOPE=gateway

4. Find your account subdomain in the Checkout.com Dashboard under Developers → Overview. It is required for correct routing to your account-specific API endpoint.

5. Import and initialize in your application entry point:

import { Checkout } from './lib/checkout-sdk/index.js';

const cko = new Checkout('sk_sbox_...', {
    pk: 'pk_sbox_...',
    subdomain: 'YOUR_PREFIX',
});

Public API

Checkout

class Checkout {
    constructor(secretKey: string, options?: {
        pk?: string;
        client?: string;
        scope?: string | string[];
        environment?: 'sandbox' | 'production';
        subdomain?: string;
        timeout?: number;
    });

    payments: Payments;
    instruments: Instruments;
    disputes: Disputes;
    webhooks: Webhooks;
    events: Events;
    customers: Customers;
    issuing: Issuing;
    reconciliation: Reconciliation;
    // ... all other API modules
}

The main entry point. Instantiate once per application and share the instance. The constructor resolves authentication automatically via AuthBuilder: if OAuth env vars are present they take precedence; otherwise static key options are used.

AuthBuilder

class AuthBuilder {
    static build(key: string | null, options: Record<string, any>): {
        sk?: string;
        pk?: string;
        secret?: string;
        client?: string;
        scope?: string;
        host?: string;
        environment?: Environment;
        environmentSubdomain?: EnvironmentSubdomain;
        access?: null;
    };
    static buildFromOAuthEnvVars(options: Record<string, any>): object;
    static buildFromStaticKeyEnvVars(key: string | null, options: Record<string, any>): object;
    static buildFromOAuthOptions(key: string, options: Record<string, any>): object;
    static buildFromStaticKeyOptions(key: string, options: Record<string, any>): object;
}

Not called directly by consumers, but useful to understand how credentials are resolved. Priority order: OAuth env vars → static key env vars → OAuth declared options → static key declared options.

EnvironmentSubdomain

class EnvironmentSubdomain {
    constructor(environment: Environment, subdomain: string);
    getCheckoutApi(): string;
    getOAuthAuthorizationApi(): string;
    static createUrlWithSubdomain(originalUrl: string, subdomain: string): string;
    static isValidSubdomain(subdomain: string): boolean;
}

Prepends an account-specific subdomain to the environment base URLs. Use when your Checkout.com account requires a custom prefix (all accounts since recent API versions). isValidSubdomain validates lowercase alphanumeric format only.

Working examples

Scenario - Create a card payment with static API keys

Initialize using declared options and request a one-time card payment. This is the most common integration path for server-side checkout flows.

import { Checkout } from './lib/checkout-sdk/index.js';

const cko = new Checkout('sk_sbox_xxxxxxxxxxxxxxxx', {
    pk: 'pk_sbox_xxxxxxxxxxxxxxxx',
    subdomain: 'mycompany',
});

const payment = await cko.payments.request({
    source: {
        type: 'card',
        number: '4242424242424242',
        expiry_month: 12,
        expiry_year: 2030,
        cvv: '100',
    },
    amount: 1000,   // in minor units (pence, cents)
    currency: 'GBP',
    reference: 'order-001',
});

console.log(payment.id);        // pay_xxxxx
console.log(payment.status);    // Authorized

Scenario - OAuth authentication with scoped access

Use OAuth credentials when your application requires fine-grained scope control, such as restricting a service to only dispute management. The SDK handles token acquisition and refresh automatically.

import { Checkout } from './lib/checkout-sdk/index.js';

const cko = new Checkout('your_api_secret', {
    client: 'ack_xxxxxxxxxxxxxxxx',
    pk: 'pk_sbox_xxxxxxxxxxxxxxxx',
    scope: ['gateway', 'disputes:view', 'disputes:provide-evidence'],
    environment: 'sandbox',
    subdomain: 'mycompany',
});

// List open disputes
const disputes = await cko.disputes.get({
    statuses: 'evidence_required',
    limit: 10,
});

console.log(disputes.total_count);
disputes.data.forEach(d => console.log(d.id, d.status));

Scenario - Environment variable based initialization in a production service

Load credentials from the environment so that secrets are never hard-coded. This is the recommended pattern for containerized deployments.

// .env (loaded by dotenv or your platform's secret manager):
// CKO_SECRET_KEY=sk_xxxxxxxx
// CKO_PUBLIC_KEY=pk_xxxxxxxx

import { Checkout } from './lib/checkout-sdk/index.js';

// No keys passed; AuthBuilder reads CKO_SECRET_KEY from process.env
const cko = new Checkout(null, { subdomain: 'mycompany' });

// Create a customer record
const customer = await cko.customers.create({
    email: 'alice@example.com',
    name: 'Alice Example',
});

// Store a payment instrument for that customer
const instrument = await cko.instruments.create({
    type: 'token',
    token: 'tok_sbox_xxxxxxxx',
    customer: { id: customer.id },
});

console.log(instrument.id);   // src_xxxxxxxx

File walkthrough

• source/index.js - Barrel file; re-exports every API class and the Checkout default. Import from here in application code.
• source/Checkout.js - Instantiates AuthBuilder, constructs the HTTP client, and attaches all API module instances as properties.
• source/auth-builder.js - Four static factory methods covering every credential permutation; selects strategy via env-var presence and option shape.
• source/config.js - All hard-coded constants: base URLs for every service, key validation regexes, CURRENCIES map, PAYMENT_TYPES map, default timeout (15 000 ms).
• source/Environment.js - Immutable value object pairing a checkout API URL with an OAuth URL; sandbox and production singletons.
• source/EnvironmentSubdomain.js - Wraps Environment and rewrites hosts to include an account subdomain prefix; validates subdomain format.
• source/endpoints-factory.js - Creates and returns configured instances of every API module; called by Checkout.js during construction.
• source/special-urls.js - Maps service names (transfers, balances, forward, files) to their non-standard hostnames; consumed by the HTTP client.
• source/api/ - Per-domain API modules (payments, instruments, disputes, issuing, etc.); each exposes methods matching the Checkout.com REST API.
• source/services/ - HTTP transport layer and access-token refresh logic shared by all API modules.

Common pitfalls and fixes

• ESM/CJS conflict: The source uses export/import. If your project uses require(), set "type": "module" in package.json or compile with tsc/esbuild targeting CommonJS.
• Missing subdomain: Omitting subdomain routes requests to the generic base URL, which may return 404 or wrong-account errors. Always supply the prefix found in Dashboard → Developers → Overview.
• Env var precedence overrides explicit keys: CKO_SECRET and CKO_SECRET_KEY in process.env take precedence over constructor arguments. Unset them in development if you want to use hardcoded test keys.
• Scope must be an array or string: Passing scope as neither causes the OAuth token request to fail. Use ['gateway'] or 'gateway'; both are accepted.
• Token not refreshed in long-running processes: The SDK manages OAuth token expiry internally, but the Checkout instance must be shared across requests rather than recreated per request, or tokens are fetched on every call.
• axios version mismatch: The SDK imports axios directly. If your project pins an incompatible major version (e.g., axios v0.x vs v1.x), install a compatible version alongside or deduplicate with npm dedupe.

Vibe-coding prompt template

I have the Checkout.com Node.js SDK source located at `source/` in my project root.
There is a `USAGE.md` in the same directory with full API documentation and working examples.
The upstream package is `user@example.com`.

Please integrate this SDK into my existing project by:
1. Reading `USAGE.md` and `source/index.js` to understand available exports.
2. Installing required dependencies: axios, form-data.
3. Creating an initializer module that reads credentials from environment variables
   and exposes a shared `cko` instance.
4. Wiring the following features into my application: [LIST YOUR FEATURES HERE,
   e.g. "create payments", "list disputes", "manage webhooks"].
5. Adding error handling for API errors returned by the SDK.
6. Showing me where to place my account subdomain and how to obtain it.

Only use exports that appear in `source/index.js`. Do not install the npm package;
use the local `source/` directory instead.

License and credit

The upstream project is licensed under the MIT License; see source/LICENSE if present in the copied directory. Source: checkout-sdk-node on npm and checkout/checkout-sdk-node on GitHub.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Adyen Node.js API Library for Payment Integration

eCommerce, Marketplace & POS Systems

Free