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.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Adyen Node.js API Library for Payment Integration

eCommerce, Marketplace & POS Systems

무료