Skip to content

checkout/checkout-sdk-node

BranchesTags

Repository files navigation

build-status CI Tests CodeQL codecov GitHub release npm version

zip badge

npm start

Checkout.com Node.js SDK

The official Node.js SDK for Checkout.com payment gateway.

Table of Contents

Features

  • ✅ Full API Coverage - Support for all Checkout.com API endpoints
  • ✅ TypeScript Support - Includes TypeScript definitions
  • ✅ Dual Authentication - API Keys and OAuth/Access Credentials
  • ✅ High Test Coverage - 97.95% code coverage with 816 tests
  • ✅ Modern Node.js - Built for Node.js 18+
  • ✅ Flexible HTTP Client - Use native fetch or axios
  • ✅ Promise-based - Async/await support
  • ✅ Comprehensive Error Handling - Detailed error types

Requirements

  • Node.js >= 18.0.0
  • npm or yarn

⚠️ Important: Each Checkout.com account has its own unique base URL prefix. You must configure this prefix when initializing the SDK to connect to your specific account. Find your unique prefix in the Dashboard → Developers → Overview. See Base URL Configuration for details.

⚠️ Deprecation Notice: Initializing the SDK without the subdomain parameter is deprecated and will be removed in a future major version. Please ensure you provide your account-specific subdomain to avoid disruption when upgrading.

🚀 Install

npm install checkout-sdk-node

💻 Import

// ES6:
import { Checkout } from 'checkout-sdk-node';
// Common JS:
const { Checkout } = require('checkout-sdk-node');

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

🎬 Initialize SDK

Initialization Methods

The SDK supports 4 ways to initialize, depending on your authentication method and credential storage:

1. Static Keys (API Keys) - Declared Options

Use when you have sk_XXX and pk_XXX keys and want to pass them directly:

const cko = new Checkout('sk_sbox_...', {
    pk: 'pk_sbox_...',
    subdomain: 'YOUR_PREFIX'  // Required: Get from Dashboard → Developers → Overview
});

Required:

  • First parameter: Secret Key (sk_XXX)
  • pk: Public Key (pk_XXX) - Required
  • subdomain: Account prefix - Required

2. OAuth (Access Credentials) - Declared Options

Use when you have ack_XXXX access credentials and want to pass them directly:

const cko = new Checkout('your_api_secret', {
    client: 'ack_XXXXXXXX',
    pk: 'pk_sbox_...',          // Required for OAuth
    scope: ['gateway'],         // Required - scopes your app needs
    environment: 'sandbox',     // 'sandbox' or 'production'
    subdomain: 'YOUR_PREFIX'    // Required: Get from Dashboard → Developers → Overview
});

Required:

  • First parameter: API Secret (OAuth secret)
  • client: Access credential ID (ack_XXXX) - Triggers OAuth mode
  • pk: Public Key - Required for OAuth
  • scope: OAuth scopes (array or string) - Required
  • environment: 'sandbox' or 'production' - Required
  • subdomain: Account prefix - Required

3. Static Keys (API Keys) - Environment Variables

Use when you have sk_XXX and pk_XXX in environment variables and want zero-config:

Set environment variables:

export CKO_SECRET_KEY=sk_sbox_...
export CKO_PUBLIC_KEY=pk_sbox_...

Initialize:

const cko = new Checkout(null, {
    subdomain: 'YOUR_PREFIX'  // Must be passed explicitly
});

Environment Variables:

  • CKO_SECRET_KEY: Secret Key (sk_XXX)
  • CKO_PUBLIC_KEY: Public Key (pk_XXX) - Optional

4. OAuth (Access Credentials) - Environment Variables

Use when you have OAuth credentials in environment variables:

Set environment variables:

export CKO_SECRET=your_api_secret
export CKO_CLIENT=ack_XXXXXXXX
export CKO_SCOPE=gateway,vault
export CKO_ENVIRONMENT=sandbox

Initialize:

const cko = new Checkout(null, {
    subdomain: 'YOUR_PREFIX'  // Must be passed explicitly
});

Environment Variables:

  • CKO_SECRET: API Secret (OAuth secret) - Triggers OAuth mode
  • CKO_CLIENT: Access credential ID (ack_XXXX)
  • CKO_SCOPE: OAuth scopes - Optional, defaults to 'gateway'
  • CKO_ENVIRONMENT: 'sandbox' or 'production' - Optional

Important Notes

⚠️ Subdomain is always required: The subdomain option must be passed explicitly when initializing the SDK. It cannot be set via environment variables. Find your unique prefix in Dashboard → Developers → Overview.

Set custom config

Besides the authentication, you also have the option to configure some extra elements about the SDK

const cko = new Checkout('...', {
    ..., //other authentication config
    host: "https://myProxyExample.com", // in case you need to use a custom host for tests
    timeout: 60000,   // HTTP request timeout in ms
    agent: new http.Agent({ keepAlive: true }), // custom HTTP agent
    httpClient: 'axios' // specify axios httpClient, by default fetch. Optional
});

HTTP Client Configuration

The SDK supports two HTTP clients: fetch (default) and axios.

Using Fetch (Default)

By default, the SDK uses the native fetch API available in Node.js 18+. No additional configuration is needed:

const cko = new Checkout('sk_sbox_...', {
    pk: 'pk_sbox_...'
    // fetch is used by default
});

Using Axios

To use axios instead, install it and specify it in the configuration:

npm install axios
import https from 'https';

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

// With custom agent for connection pooling
const ckoWithAgent = new Checkout('sk_sbox_...', {
    pk: 'pk_sbox_...',
    httpClient: 'axios',
    agent: new https.Agent({ 
        keepAlive: true,
        maxSockets: 50 
    })
});

When to use Axios:

  • Node.js versions below 18 (fetch not available)
  • Advanced connection pooling requirements
  • Custom SSL/TLS configurations
  • Proxy configurations with specific needs

Base URL Configuration (Account-Specific)

Important: The base URLs for Checkout.com APIs are unique to your account. Each account has a specific prefix (the first 8 characters of your client_id, excluding the cli_ prefix) that must be used in all API requests.

⚠️ Deprecation Warning: When initializing the SDK without the subdomain parameter, a deprecation warning will be logged to the console. This functionality is deprecated and will be removed in a future major version. Always provide your account-specific subdomain to ensure compatibility with future releases.

Finding Your Unique Base URL

  1. Sign in to your Checkout.com Dashboard
  2. Navigate to Developers → Overview
  3. Your unique base URL is displayed on the Developer overview page
    • Example: https://vkuhvk4v.api.checkout.com
  4. Alternatively: Go to Settings → Account details → Connection settings

Prefix Requirements

  • Must be alphanumeric (lowercase letters and numbers only)
  • Typically 8 characters (first 8 of your client_id)
  • No special characters, spaces, or uppercase letters
  • Obtain from Dashboard or contact your account manager

Base URL Formats

These formats match the Checkout.com API Reference – Base URLs and the OpenAPI servers in the project's swagger-spec.json.

Sandbox:

  • API Base URL: https://{prefix}.api.sandbox.checkout.com
  • OAuth Authorization: https://{prefix}.access.sandbox.checkout.com/connect/token

Production:

  • API Base URL: https://{prefix}.api.checkout.com
  • OAuth Authorization: https://{prefix}.access.checkout.com/connect/token

See Initialization Methods above for examples of how to configure your SDK with the correct prefix.

Special Service URLs

The following services use dedicated subdomains that are not affected by your account prefix:

  • Balances: https://balances.{environment}.checkout.com
  • Files: https://files.{environment}.checkout.com
  • Forward: https://forward.{environment}.checkout.com
  • Identity Verification: https://identity-verification.api.{environment}.checkout.com
  • Transfers: https://transfers.{environment}.checkout.com

These services use fixed URLs and do not require subdomain configuration.

Note: If you are unsure of your client ID or base URL for either environment, contact your account manager or request support

🔧 SDK Environment (Sandbox/Production)

When using API Keys (pk_XXX + sk_XXX) the SDK will automatically figure out what environment you are using however, if you use access credentials (ack_XXXX), make sure you set the "environment" in the config, as shown above in the initialization.

💡 Quick Examples

Here are some common operations to get you started. All examples assume you have already initialized the SDK with your credentials and subdomain:

const cko = new Checkout('sk_sbox_...', {
    pk: 'pk_sbox_...',
    subdomain: 'YOUR_PREFIX'  // Your unique prefix from Dashboard
});

Processing a Payment

const payment = await cko.payments.request({
    source: {
        type: 'token',
        token: 'tok_4gzeau5o2uqubbk6fufs3m7p54'
    },
    amount: 1000, // Amount in minor units (e.g., cents)
    currency: 'USD',
    reference: 'ORD-5023-4E89',
    customer: {
        email: 'customer@example.com',
        name: 'John Doe'
    }
});

console.log('Payment ID:', payment.id);
console.log('Status:', payment.status);

Retrieving Payment Details

const paymentDetails = await cko.payments.get('pay_mbabizu24mvu3mela5njyhpit4');

console.log('Payment Status:', paymentDetails.status);
console.log('Amount:', paymentDetails.amount);

Processing a Refund

const refund = await cko.payments.refund('pay_mbabizu24mvu3mela5njyhpit4', {
    amount: 500, // Partial refund
    reference: 'Refund for order 5023'
});

console.log('Refund ID:', refund.action_id);

Creating a Customer

const customer = await cko.customers.create({
    email: 'customer@example.com',
    name: 'John Doe',
    phone: {
        country_code: '+1',
        number: '4155552671'
    }
});

console.log('Customer ID:', customer.id);

Managing Webhooks

// Register a webhook
const webhook = await cko.webhooks.register({
    url: 'https://example.com/webhooks',
    event_types: ['payment_captured', 'payment_declined']
});

// Retrieve webhooks
const webhooks = await cko.webhooks.retrieveWebhooks();

TypeScript Support

The SDK includes TypeScript definitions out of the box. No need to install additional @types packages.

import { Checkout } from 'checkout-sdk-node';
import type { PaymentRequest, PaymentResponse } from 'checkout-sdk-node';

const cko: Checkout = new Checkout('sk_sbox_...', {
    pk: 'pk_sbox_...',
    subdomain: 'YOUR_PREFIX'  // Your unique prefix from Dashboard
});

const paymentRequest: PaymentRequest = {
    source: {
        type: 'token',
        token: 'tok_4gzeau5o2uqubbk6fufs3m7p54'
    },
    amount: 1000,
    currency: 'USD'
};

const payment: PaymentResponse = await cko.payments.request(paymentRequest);

📦 Available Endpoints

The SDK provides access to all Checkout.com API endpoints:

Module Description Access
Access OAuth token management cko.access
Account Updater Real-time account updater cko.accountUpdater
Apple Pay Apple Pay certificate management cko.applePay
Balances Query entity balances cko.balances
Baloto ⚠️ Deprecated - Use cko.payments instead cko.baloto
Boleto ⚠️ Deprecated - Use cko.payments instead cko.boleto
Card Metadata Retrieve card metadata and BIN data cko.cardMetadata
Customers Manage customer profiles cko.customers
Disputes Handle payment disputes and chargebacks cko.disputes
Events Retrieve payment and dispute events cko.events
Fawry ⚠️ Deprecated - Use cko.payments instead cko.fawry
Files Upload and manage files cko.files
Financial Financial actions and operations cko.financial
Forex Foreign exchange rates cko.forex
Forward Forward API requests cko.forward
Giropay ⚠️ Deprecated - Use cko.payments instead cko.giropay
Hosted Payments Create hosted payment pages cko.hostedPayments
iDEAL ⚠️ Deprecated - Use cko.payments instead cko.ideal
Identities Identity verification cko.identities
Instruments Store and manage payment instruments cko.instruments
Issuing Card issuing operations cko.issuing
Klarna ⚠️ Deprecated - Use cko.payments instead cko.klarna
Network Tokens Network tokenization cko.networkTokens
OXXO ⚠️ Deprecated - Use cko.payments instead cko.oxxo
Pago Fácil ⚠️ Deprecated - Use cko.payments instead cko.pagoFacil
Payment Contexts Create and manage payment contexts cko.paymentContexts
Payment Links Generate payment links cko.paymentLinks
Payment Methods Query available payment methods cko.paymentMethods
Payments Process, capture, void, and refund payments cko.payments
Payment Sessions Create and manage payment sessions cko.paymentSessions
Payment Setups Create and manage payment setups cko.paymentSetups
Platforms Platform and sub-entity management cko.platforms
Rapipago ⚠️ Deprecated - Use cko.payments instead cko.rapipago
Reconciliation Access payment reconciliation data cko.reconciliation
Reports Generate and retrieve reports cko.reports
Risk Manage risk assessments cko.risk
SEPA ⚠️ Deprecated - Use cko.payments instead cko.sepa
Sessions Create payment and 3DS sessions cko.sessions
Sources Create and manage payment sources cko.sources
Tokens Request payment tokens cko.tokens
Transfers Manage payout transfers cko.transfers
Webhooks Configure webhook endpoints cko.webhooks
Workflows Create and manage payment workflows cko.workflows

Note on Alternative Payment Methods (APMs): The specific APM endpoints (Baloto, Boleto, Fawry, Giropay, iDEAL, Klarna, OXXO, Pago Fácil, Rapipago, SEPA) are deprecated. Please use the unified cko.payments endpoint with the appropriate payment source type instead. See the API Reference for examples.

⁉️ Error handling

The SDK is using promises, and you can handle errors similar to any other HTTP call.

try {
    // some async request made with the SDK
    const action = await cko.payments.request({...});
    ...
} catch (error) {
    console.log(error.name, error.http_code, error.body)
    switch (error.name) {
        ...
    }
}

Here you have all the possible SDK specific errors:

error.name error.http_code error.body
AuthenticationError 401 object
ActionNotAllowed 403 object
UrlAlreadyRegistered 409 undefined
NotFoundError 404 object
BadGateway 502 undefined
ValidationError 422 object
TooManyRequestsError 429 object/undefined
ValueError 429 string describing error

✅ Testing

The SDK comes with comprehensive test coverage (97.95% with 816 tests).

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm test

# View coverage report
open coverage/index.html

Test Structure

  • Unit Tests - Mock all HTTP calls using nock
  • Integration Tests - Test against real API (requires valid credentials)
  • Coverage - 97.95% statements, 90.83% branches, 100% functions

📖 Examples of usage

You can see examples of how to use the SDK for every endpoint documented in our API Reference. All you have to do is to navigate to the endpoint you want to use, and select "Node" for the example on the right side.

NOTE: If you use access credentials (ack_XXXX) the link to the API reference relevant to you will be shared by your Solutions Engineers.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to get started.

License

MIT License - see LICENSE for details.

Support

About

Checkout.com SDK for Node.js. Documentation here:

api-reference.checkout.com

Topics

sdk credit-card api-client payments online-payments payment-gateway payment-processing payouts sdk-nodejs card-processing node-js-payments accept-card-payments

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

66 stars

Watchers

9 watching

Forks

21 forks
Report repository

Releases 36

3.1.0 Latest
Jan 30, 2026
+ 35 releases

Packages

 
 
 

Contributors

Languages