\n\n# Checkout.com Node.js SDK\n\nThe official Node.js SDK for [Checkout.com](https://www.checkout.com) payment gateway.\n\n## Table of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#rocket-install)\n- [Getting Started](#clapper-initialize-sdk)\n - [Authentication](#with-api-keys-or-access-credentials)\n - [Environment Variables](#with-environment-variables)\n - [Custom Configuration](#set-custom-config)\n - [HTTP Client Configuration](#http-client-configuration)\n - [Base URL Configuration](#base-url-configuration-account-specific)\n- [SDK Environment](#wrench-sdk-environment-sandboxproduction)\n- [Quick Examples](#bulb-quick-examples)\n- [TypeScript Support](#typescript-support)\n- [Available Endpoints](#package-available-endpoints)\n- [Error Handling](#interrobang-error-handling)\n- [Testing](#white_check_mark-testing)\n- [Documentation](#book-examples-of-usage)\n- [Migration Guide](MIGRATION.md)\n\n## Features\n\n- ✅ **Full API Coverage** - Support for all Checkout.com API endpoints\n- ✅ **TypeScript Support** - Includes TypeScript definitions\n- ✅ **Dual Authentication** - API Keys and OAuth/Access Credentials\n- ✅ **High Test Coverage** - 97.95% code coverage with 816 tests\n- ✅ **Modern Node.js** - Built for Node.js 18+\n- ✅ **Flexible HTTP Client** - Use native fetch or axios\n- ✅ **Promise-based** - Async/await support\n- ✅ **Comprehensive Error Handling** - Detailed error types\n\n## Requirements\n\n- Node.js >= 18.0.0\n- npm or yarn\n\n> **⚠️ 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](https://dashboard.checkout.com/developers). See [Base URL Configuration](#base-url-configuration-account-specific) for details.\n\n> **⚠️ Breaking change in the next major release:** Initializing the SDK without the `subdomain` parameter used to emit a deprecation warning. It now throws. You must either set `subdomain`, or explicitly opt out with `useLegacyDomain: true`, which is itself deprecated and exists only for emergencies. See [Legacy domain (emergency use only)](#legacy-domain-emergency-use-only).\n\n### Subdomain value\n\nRequests 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`, and 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](https://api-reference.checkout.com/#section/Base-URLs) and [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints) for further details, and for where to find your unique client ID.\n\n# :rocket: Install\n\n```bash\nnpm install checkout-sdk-node\n```\n\n# :computer: Import\n\n```js\n// ES6:\nimport { Checkout } from 'checkout-sdk-node';\n// Common JS:\nconst { Checkout } = require('checkout-sdk-node');\n```\n\n> If you don't have your API keys, you can sign up for a test account [here](https://www.checkout.com/get-test-account).\n\n# :clapper: Initialize SDK\n\n## Initialization Methods\n\nThe SDK supports 4 ways to initialize, depending on your authentication method and credential storage:\n\n### 1. Static Keys (API Keys) - Declared Options\n\nUse when you have `sk_XXX` and `pk_XXX` keys and want to pass them directly:\n\n```js\nconst cko = new Checkout('sk_sbox_...', {\n pk: 'pk_sbox_...',\n subdomain: 'YOUR_PREFIX' // Required: Get from Dashboard → Developers → Overview\n});\n```\n\n**Required:**\n- First parameter: Secret Key (sk_XXX)\n- `pk`: Public Key (pk_XXX) - Required\n- `subdomain`: Account prefix - Required\n\n### 2. OAuth (Access Credentials) - Declared Options\n\nUse when you have `ack_XXXX` access credentials and want to pass them directly:\n\n```js\nconst cko = new Checkout('your_api_secret', {\n client: 'ack_XXXXXXXX',\n pk: 'pk_sbox_...', // Required for OAuth\n scope: ['gateway'], // Required - scopes your app needs\n environment: 'sandbox', // 'sandbox' or 'production'\n subdomain: 'YOUR_PREFIX' // Required: Get from Dashboard → Developers → Overview\n});\n```\n\n**Required:**\n- First parameter: API Secret (OAuth secret)\n- `client`: Access credential ID (ack_XXXX) - Triggers OAuth mode\n- `pk`: Public Key - Required for OAuth\n- `scope`: OAuth scopes (array or string) - Required\n- `environment`: 'sandbox' or 'production' - Required\n- `subdomain`: Account prefix - Required\n\n#### Scope constants\n\n`OAuthScopes` exposes every scope the Checkout.com API documents, so you don't have to hardcode the\nwire strings. Plain strings still work exactly as before — this is optional:\n\n```js\nimport { Checkout, OAuthScopes } from 'checkout-sdk-node';\n\nconst cko = new Checkout('your_api_secret', {\n client: 'ack_XXXXXXXX',\n pk: 'pk_sbox_...',\n scope: [OAuthScopes.GATEWAY, OAuthScopes.VAULT, OAuthScopes.FX],\n environment: 'sandbox',\n subdomain: 'YOUR_PREFIX'\n});\n```\n\nTypeScript users can import the `OAuthScope` union to type their own scope lists:\n\n```ts\nimport { OAuthScopes, type OAuthScope } from 'checkout-sdk-node';\n\nconst scopes: OAuthScope[] = [OAuthScopes.DISPUTES_VIEW, OAuthScopes.FILES_RETRIEVE];\n```\n\n> The token endpoint rejects the **entire** request if any one requested scope is undefined, so a\n> single typo costs you every other scope you asked for. That is what these constants are for.\n\n### 3. Static Keys (API Keys) - Environment Variables\n\nUse when you have `sk_XXX` and `pk_XXX` in environment variables and want zero-config:\n\nSet environment variables:\n```bash\nexport CKO_SECRET_KEY=sk_sbox_...\nexport CKO_PUBLIC_KEY=pk_sbox_...\n```\n\nInitialize:\n```js\nconst cko = new Checkout(null, {\n subdomain: 'YOUR_PREFIX' // Must be passed explicitly\n});\n```\n\n**Environment Variables:**\n- `CKO_SECRET_KEY`: Secret Key (sk_XXX)\n- `CKO_PUBLIC_KEY`: Public Key (pk_XXX) - Optional\n\n### 4. OAuth (Access Credentials) - Environment Variables\n\nUse when you have OAuth credentials in environment variables:\n\nSet environment variables:\n```bash\nexport CKO_SECRET=your_api_secret\nexport CKO_CLIENT=ack_XXXXXXXX\nexport CKO_SCOPE=gateway,vault\nexport CKO_ENVIRONMENT=sandbox\n```\n\nInitialize:\n```js\nconst cko = new Checkout(null, {\n subdomain: 'YOUR_PREFIX' // Must be passed explicitly\n});\n```\n\n**Environment Variables:**\n- `CKO_SECRET`: API Secret (OAuth secret) - Triggers OAuth mode\n- `CKO_CLIENT`: Access credential ID (ack_XXXX)\n- `CKO_SCOPE`: OAuth scopes - Optional, defaults to 'gateway'\n- `CKO_ENVIRONMENT`: 'sandbox' or 'production' - Optional\n\n### Important Notes\n\n> **⚠️ 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](https://dashboard.checkout.com/developers). Initialization throws a `ValueError` if neither `subdomain` nor `useLegacyDomain` is set, or if both are.\n\n> A custom `host` replaces the base URL outright, so neither option is required when you pass one. Previous (ABC) keys predate merchant-specific subdomains and are exempt.\n\n## Set custom config\nBesides the authentication, you also have the option to configure some extra elements about the SDK \n```js\nconst cko = new Checkout('...', {\n ..., //other authentication config\n host: \"https://myProxyExample.com\", // in case you need to use a custom host for tests\n timeout: 60000, // HTTP request timeout in ms\n agent: new http.Agent({ keepAlive: true }), // custom HTTP agent\n httpClient: 'axios' // specify axios httpClient, by default fetch. Optional\n});\n```\n\n## HTTP Client Configuration\n\nThe SDK supports two HTTP clients: **fetch** (default) and **axios**.\n\n### Using Fetch (Default)\n\nBy default, the SDK uses the native `fetch` API available in Node.js 18+. No additional configuration is needed:\n\n```js\nconst cko = new Checkout('sk_sbox_...', {\n pk: 'pk_sbox_...'\n // fetch is used by default\n});\n```\n\n### Using Axios\n\nTo use axios instead, install it and specify it in the configuration:\n\n```bash\nnpm install axios\n```\n\n```js\nimport https from 'https';\n\nconst cko = new Checkout('sk_sbox_...', {\n pk: 'pk_sbox_...',\n httpClient: 'axios'\n});\n\n// With custom agent for connection pooling\nconst ckoWithAgent = new Checkout('sk_sbox_...', {\n pk: 'pk_sbox_...',\n httpClient: 'axios',\n agent: new https.Agent({ \n keepAlive: true,\n maxSockets: 50 \n })\n});\n```\n\n**When to use Axios:**\n- Node.js versions below 18 (fetch not available)\n- Advanced connection pooling requirements\n- Custom SSL/TLS configurations\n- Proxy configurations with specific needs\n\n## Base URL Configuration (Account-Specific)\n\n**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.\n\n> **⚠️ 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.\n\n### Finding Your Unique Base URL\n\n1. Sign in to your [Checkout.com Dashboard](https://dashboard.checkout.com)\n2. Navigate to **Developers → Overview**\n3. Your unique base URL is displayed on the Developer overview page\n - Example: `https://vkuhvk4v.api.checkout.com`\n4. Alternatively: Go to **Settings → Account details** → Connection settings\n\n### Prefix Requirements\n\n- Must be alphanumeric (lowercase letters and numbers only)\n- Typically 8 characters (first 8 of your client_id)\n- No special characters, spaces, or uppercase letters\n- Obtain from Dashboard or contact your account manager\n\n### Base URL Formats\n\nThese formats match the [Checkout.com API Reference – Base URLs](https://api-reference.checkout.com/#section/Base-URLs) and the OpenAPI `servers` in the project's `swagger-spec.json`.\n\n**Sandbox:**\n- API Base URL: `https://{prefix}.api.sandbox.checkout.com`\n- OAuth Authorization: `https://{prefix}.access.sandbox.checkout.com/connect/token`\n\n**Production:**\n- API Base URL: `https://{prefix}.api.checkout.com`\n- OAuth Authorization: `https://{prefix}.access.checkout.com/connect/token`\n\nSee [Initialization Methods](#initialization-methods) above for examples of how to configure your SDK with the correct prefix.\n\n### Special Service URLs\n\nThe following services use dedicated subdomains that are **not affected** by your account prefix:\n\n- **Balances**: `https://balances.{environment}.checkout.com`\n- **Files**: `https://files.{environment}.checkout.com`\n- **Forward**: `https://forward.{environment}.checkout.com`\n- **Identity Verification**: `https://identity-verification.api.{environment}.checkout.com`\n- **Transfers**: `https://transfers.{environment}.checkout.com`\n\nThese services use fixed URLs and do not require subdomain configuration.\n\n**Note:** If you are unsure of your client ID or base URL for either environment, contact your account manager or [request support](https://www.checkout.com/docs/support)\n\n# :wrench: SDK Environment (Sandbox/Production)\nWhen 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. \n\n# :bulb: Quick Examples\n\nHere are some common operations to get you started. All examples assume you have already initialized the SDK with your credentials and subdomain:\n\n```js\nconst cko = new Checkout('sk_sbox_...', {\n pk: 'pk_sbox_...',\n subdomain: 'YOUR_PREFIX' // Your unique prefix from Dashboard\n});\n```\n\n## Processing a Payment\n\n```js\nconst payment = await cko.payments.request({\n source: {\n type: 'token',\n token: 'tok_4gzeau5o2uqubbk6fufs3m7p54'\n },\n amount: 1000, // Amount in minor units (e.g., cents)\n currency: 'USD',\n reference: 'ORD-5023-4E89',\n customer: {\n email: 'customer@example.com',\n name: 'John Doe'\n }\n});\n\nconsole.log('Payment ID:', payment.id);\nconsole.log('Status:', payment.status);\n```\n\n## Retrieving Payment Details\n\n```js\nconst paymentDetails = await cko.payments.get('pay_mbabizu24mvu3mela5njyhpit4');\n\nconsole.log('Payment Status:', paymentDetails.status);\nconsole.log('Amount:', paymentDetails.amount);\n```\n\n## Processing a Refund\n\n```js\nconst refund = await cko.payments.refund('pay_mbabizu24mvu3mela5njyhpit4', {\n amount: 500, // Partial refund\n reference: 'Refund for order 5023'\n});\n\nconsole.log('Refund ID:', refund.action_id);\n```\n\n## Creating a Customer\n\n```js\nconst customer = await cko.customers.create({\n email: 'customer@example.com',\n name: 'John Doe',\n phone: {\n country_code: '+1',\n number: '4155552671'\n }\n});\n\nconsole.log('Customer ID:', customer.id);\n```\n\n## Managing Webhooks\n\n```js\n// Register a webhook\nconst webhook = await cko.webhooks.register({\n url: 'https://example.com/webhooks',\n event_types: ['payment_captured', 'payment_declined']\n});\n\n// Retrieve webhooks\nconst webhooks = await cko.webhooks.retrieveWebhooks();\n```\n\n# TypeScript Support\n\nThe SDK includes TypeScript definitions out of the box. No need to install additional `@types` packages.\n\n```typescript\nimport { Checkout } from 'checkout-sdk-node';\nimport type { PaymentRequest, PaymentResponse } from 'checkout-sdk-node';\n\nconst cko: Checkout = new Checkout('sk_sbox_...', {\n pk: 'pk_sbox_...',\n subdomain: 'YOUR_PREFIX' // Your unique prefix from Dashboard\n});\n\nconst paymentRequest: PaymentRequest = {\n source: {\n type: 'token',\n token: 'tok_4gzeau5o2uqubbk6fufs3m7p54'\n },\n amount: 1000,\n currency: 'USD'\n};\n\nconst payment: PaymentResponse = await cko.payments.request(paymentRequest);\n```\n\n# :package: Available Endpoints\n\nThe SDK provides access to all Checkout.com API endpoints:\n\n| Module | Description | Access |\n|--------|-------------|--------|\n| **Access** | OAuth token management | `cko.access` |\n| **Account Updater** | Real-time account updater | `cko.accountUpdater` |\n| **Apple Pay** | Apple Pay certificate management | `cko.applePay` |\n| **Bacs Direct Debit** | Send Bacs Direct Debit pre-notifications | `cko.bacs` |\n| **Balances** | Query entity balances | `cko.balances` |\n| **~~Baloto~~** | ⚠️ **Deprecated** - Use `cko.payments` instead | ~~`cko.baloto`~~ |\n| **~~Boleto~~** | ⚠️ **Deprecated** - Use `cko.payments` instead | ~~`cko.boleto`~~ |\n| **Card Metadata** | Retrieve card metadata and BIN data | `cko.cardMetadata` |\n| **Customers** | Manage customer profiles | `cko.customers` |\n| **Disputes** | Handle payment disputes and chargebacks | `cko.disputes` |\n| **Events** | Retrieve payment and dispute events | `cko.events` |\n| **~~Fawry~~** | ⚠️ **Deprecated** - Use `cko.payments` instead | ~~`cko.fawry`~~ |\n| **Files** | Upload and manage files | `cko.files` |\n| **Financial** | Financial actions and operations | `cko.financial` |\n| **Forex** | Foreign exchange rates | `cko.forex` |\n| **Forward** | Forward API requests | `cko.forward` |\n| **~~Giropay~~** | ⚠️ **Deprecated** - Use `cko.payments` instead | ~~`cko.giropay`~~ |\n| **Hosted Payments** | Create hosted payment pages | `cko.hostedPayments` |\n| **~~iDEAL~~** | ⚠️ **Deprecated** - Use `cko.payments` instead | ~~`cko.ideal`~~ |\n| **Identities** | Identity verification | `cko.identities` |\n| **Instruments** | Store and manage payment instruments | `cko.instruments` |\n| **Issuing** | Card issuing operations | `cko.issuing` |\n| **~~Klarna~~** | ⚠️ **Deprecated** - Use `cko.payments` instead | ~~`cko.klarna`~~ |\n| **Network Tokens** | Network tokenization | `cko.networkTokens` |\n| **~~OXXO~~** | ⚠️ **Deprecated** - Use `cko.payments` instead | ~~`cko.oxxo`~~ |\n| **~~Pago Fácil~~** | ⚠️ **Deprecated** - Use `cko.payments` instead | ~~`cko.pagoFacil`~~ |\n| **Payment Contexts** | Create and manage payment contexts | `cko.paymentContexts` |\n| **Payment Links** | Generate payment links | `cko.paymentLinks` |\n| **Payment Methods** | Query available payment methods | `cko.paymentMethods` |\n| **Payments** | Process, capture, void, and refund payments | `cko.payments` |\n| **Payment Sessions** | Create and manage payment sessions | `cko.paymentSessions` |\n| **Payment Setups** | Create and manage payment setups | `cko.paymentSetups` |\n| **Platforms** | Platform and sub-entity management | `cko.platforms` |\n| **~~Rapipago~~** | ⚠️ **Deprecated** - Use `cko.payments` instead | ~~`cko.rapipago`~~ |\n| **Reconciliation** | Access payment reconciliation data | `cko.reconciliation` |\n| **Reports** | Generate and retrieve reports | `cko.reports` |\n| **Risk** | Manage risk assessments | `cko.risk` |\n| **~~SEPA~~** | ⚠️ **Deprecated** - Use `cko.payments` instead | ~~`cko.sepa`~~ |\n| **Sessions** | Create payment and 3DS sessions | `cko.sessions` |\n| **Sources** | Create and manage payment sources | `cko.sources` |\n| **Tokens** | Request payment tokens | `cko.tokens` |\n| **Transfers** | Manage payout transfers | `cko.transfers` |\n| **Webhooks** | Configure webhook endpoints | `cko.webhooks` |\n| **Workflows** | Create and manage payment workflows | `cko.workflows` |\n\n> **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](https://api-reference.checkout.com/) for examples.\n\n# :interrobang: Error handling\nThe SDK is using promises, and you can handle errors similar to any other HTTP call.\n\n```js\ntry {\n // some async request made with the SDK\n const action = await cko.payments.request({...});\n ...\n} catch (error) {\n console.log(error.name, error.http_code, error.body)\n switch (error.name) {\n ...\n }\n}\n```\nHere you have all the possible SDK specific errors:\n\n| error.name | error.http_code | error.body |\n| -------------------- | --------------- | ----------------------- |\n| AuthenticationError | 401 | object |\n| ActionNotAllowed | 403 | object |\n| UrlAlreadyRegistered | 409 | undefined |\n| NotFoundError | 404 | object |\n| BadGateway | 502 | undefined |\n| ValidationError | 422 | object |\n| TooManyRequestsError | 429 | object/undefined |\n| ValueError | 429 | string describing error |\n\n\n# :white_check_mark: Testing\n\nThe SDK comes with comprehensive test coverage (97.95% with 816 tests).\n\n## Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Run tests with coverage\nnpm test\n\n# View coverage report\nopen coverage/index.html\n```\n\n## Test Structure\n\n- **Unit Tests** - Mock all HTTP calls using `nock`\n- **Integration Tests** - Test against real API (requires valid credentials)\n- **Coverage** - 97.95% statements, 90.83% branches, 100% functions\n\n# :book: Examples of usage\n\nYou can see examples of how to use the SDK for every endpoint documented in our [API Reference](https://api-reference.checkout.com/). 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.\n> NOTE: If you use access credentials (ack_XXXX) the link to the API reference relevant to you will be shared by your Solutions Engineers.\n\n---\n\n## Legacy domain (emergency use only)\n\n> :warning: **Only use if merchant specific sub domains are causing issues.** Connecting through your merchant-specific subdomain (see [Subdomain value](#subdomain-value)) is the supported way of using the Checkout.com API, and non-subdomain usage will be deprecated.\n\nIf, in exceptional circumstances, you cannot use your merchant-specific subdomain, you can explicitly opt out with `useLegacyDomain`:\n\n```js\nconst cko = new Checkout('sk_...', {\n useLegacyDomain: true // deprecated, emergency fallback only\n});\n```\n\nThis routes requests to `api.checkout.com` (or `api.sandbox.checkout.com`) and `access.checkout.com` (or `access.sandbox.checkout.com`). The option is marked `@deprecated` in the type definitions, so editors and `tsc` will flag it. Exactly one of `subdomain` or `useLegacyDomain` must be set: initialization throws a `ValueError` if both, or neither, are. Passing a custom `host` is a third route that bypasses this requirement entirely, since it replaces the base URL outright.\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Support\n\n- 📧 Email: [support@checkout.com](mailto:support@checkout.com)\n- 📚 Documentation: [https://api-reference.checkout.com/](https://api-reference.checkout.com/)\n- 💬 Community: [GitHub Discussions](https://github.com/checkout/checkout-sdk-node/discussions)\n\n","readmeFilename":"README.md"}
![](\"https://i.ibb.co/93zwP9m/SDK-Logo.png\"){kind=logo}
\n