checkout-client

Production-grade TypeScript client for the Checkout.com API.

All 168 endpoints · OAuth 2.0 · Full-jitter retry · Idempotency · Webhook verification · Zero runtime dependencies

---

Features

100% API coverage	All 168 endpoints, 43 typed service namespaces
Zero runtime dependencies	Only Node.js built-ins (node:crypto, node:http)
Dual-module	ESM + CommonJS, full TypeScript declarations
Deep imports	checkout-client/payments, /vault, /disputes, /issuing, /webhook, /errors
OAuth 2.0	Singleflight token fetch, in-memory cache, proactive refresh 90s before expiry
Idempotency	UUID v4 auto-injected on all eligible endpoints; override per-request
Full-jitter retry	Exponential backoff on 429 + 5xx; configurable attempts and delays
AbortSignal	Pass signal to any request for cancellation and timeout control
Webhook verification	HMAC-SHA256 constant-time signature checking
AWS PrivateLink	privateLink: true → pl-{prefix}.api.checkout.com
Typed errors	CheckoutError with status predicates and full response metadata
Structured logging	Bring your own logger via the Logger interface
68 tests	Vitest, mock fetch only — zero live API calls

---

Requirements

Node.js ≥ 18 (uses native fetch and crypto.randomUUID).

---

Installation

npm install checkout-client

---

Quick start

import { CheckoutClient } from "checkout-client";

const client = new CheckoutClient({
  prefix: process.env.CHECKOUT_PREFIX!, // first 8 chars of client_id
  environment: "sandbox",
  accessKeyId: process.env.CHECKOUT_ACCESS_KEY_ID,
  accessKeySecret: process.env.CHECKOUT_ACCESS_KEY_SECRET,
});

// Request a payment
const payment = await client.payments.request({
  amount: 10_000, // GBP £100.00 in minor units
  currency: "GBP",
  source: { type: "token", token: "tok_..." },
  reference: "ORD-001",
});

// Capture it
await client.payments.capture(payment.id);

// Partial refund (£25)
await client.payments.refund(payment.id, { amount: 2_500 });

---

Authentication

OAuth 2.0 (recommended)

new CheckoutClient({
  prefix: "vkuhvk4v",
  accessKeyId: "ack_...",
  accessKeySecret: "...",
});

Tokens are fetched once, cached in-memory, and proactively refreshed 90 s before expiry. Concurrent requests coalesce onto a single in-flight token fetch.

Static secret key

new CheckoutClient({ prefix: "vkuhvk4v", secretKey: "sk_..." });

---

Configuration

import type { CheckoutConfig } from "checkout-client";

const config: CheckoutConfig = {
  prefix: "vkuhvk4v", // required
  environment: "production", // "production" | "sandbox"
  accessKeyId: "ack_...", // OAuth 2.0
  accessKeySecret: "...",
  secretKey: "sk_...", // static key (alternative to OAuth)
  publicKey: "pk_...", // tokenization only
  privateLink: false, // AWS PrivateLink
  idempotencyKeyPrefix: "myapp", // auto-key prefix: "myapp-{uuid}"
  timeoutMs: 30_000, // per-request timeout
  retry: {
    maxAttempts: 4, // 1 initial + 3 retries
    baseDelayMs: 500,
    maxDelayMs: 30_000,
  },
  fetch: customFetch, // injectable for testing/proxies
  logger: {
    debug: (msg, meta) => console.log(msg, meta),
    warn: (msg, meta) => console.warn(msg, meta),
  },
};

---

Error handling

import { CheckoutError } from "checkout-client";
// or: import { CheckoutError } from "checkout-client/errors";

try {
  await client.payments.request({ currency: "GBP" });
} catch (err) {
  if (err instanceof CheckoutError) {
    // HTTP status predicates
    err.isNotFound(); // 404
    err.isRateLimited(); // 429 — already retried maxAttempts times
    err.isConflict(); // 409 — idempotency key collision
    err.isUnauthorized(); // 401
    err.isForbidden(); // 403
    err.isValidationError(); // 422
    err.isServerError(); // 5xx

    // Rich metadata
    err.statusCode; // number
    err.requestId; // string — include in Checkout.com support tickets
    err.errorType; // e.g. "request_invalid"
    err.errorCodes; // e.g. ["amount_invalid", "currency_required"]
    err.apiMessage; // human-readable summary
    err.rawBody; // complete response body for debugging
  }
}

---

Idempotency

Cko-Idempotency-Key (UUID v4) is auto-injected on all eligible endpoints: POST /payments (and all action sub-paths), POST /payment-contexts, POST /transfers.

// Custom key — safe to retry with the same value
await client.payments.request(req, { idempotencyKey: "order-42-attempt-1" });

// Prefix auto-generated keys
new CheckoutClient({ idempotencyKeyPrefix: "myapp" });
// → "myapp-550e8400-e29b-41d4-..."

---

Retry

Full-jitter exponential backoff: delay = random(0, min(base × 2^attempt, max))

new CheckoutClient({
  retry: {
    maxAttempts: 4, // 1 initial + 3 retries
    baseDelayMs: 500,
    maxDelayMs: 30_000,
  },
});

Retried: 429, 5xx, network errors. Not retried: 4xx except 429, 409 Conflict.

---

AbortSignal

Every service method accepts { signal } as its last options argument:

const controller = new AbortController();
setTimeout(() => controller.abort(), 5_000);

const payment = await client.payments.request(
  { amount: 10_000, currency: "GBP" },
  { signal: controller.signal },
);

---

AWS PrivateLink

new CheckoutClient({ prefix: "vkuhvk4v", privateLink: true });
// → https://pl-vkuhvk4v.api.checkout.com

---

Webhook verification

import {
  verifyWebhook,
  InvalidWebhookSignatureError,
} from "checkout-client/webhook";

app.post("/webhooks/checkout", express.raw({ type: "*/*" }), (req, res) => {
  try {
    const event = verifyWebhook(
      req.headers["cko-signature"],
      req.body, // Buffer or string
      process.env.CKO_WEBHOOK_KEY!,
    );
    console.log(event.type, event.id);
    res.sendStatus(200);
  } catch (err) {
    if (err instanceof InvalidWebhookSignatureError) {
      res.sendStatus(403);
    } else {
      res.sendStatus(500);
    }
  }
});

Or import directly from the root:

import { verifyWebhook, InvalidWebhookSignatureError } from "checkout-client";

---

Custom fetch (testing, proxies, OpenTelemetry)

// Inject a custom fetch for testing
import { CheckoutClient } from "checkout-client";

const client = new CheckoutClient({
  prefix: "testpfx1",
  secretKey: "sk_test",
  fetch: async (url, init) => {
    console.log("→", url);
    return globalThis.fetch(url, init);
  },
});

---

Deep imports

Each sub-module is independently importable with full tree-shaking support:

import type { PaymentRequest, PaymentResponse } from "checkout-client/payments";
import type { FXRatesResponse } from "checkout-client/vault";
import type { Dispute } from "checkout-client/disputes";
import type { CardResponse } from "checkout-client/issuing";
import { verifyWebhook } from "checkout-client/webhook";
import { CheckoutError } from "checkout-client/errors";

---

Complete API

Namespace	Methods
client.payments	request, list, get, getActions, incrementAuthorization, cancelRetry, capture, refund, reverse, void, search
client.flow	createSession, submitSession, createAndSubmit
client.paymentLinks	create, get
client.hostedPayments	create, get
client.paymentContexts	request, get
client.paymentSetups	create, update, get, confirm
client.paymentMethods	list
client.tokens	create
client.instruments	create, get, update, delete, getBankAccountFieldFormatting
client.customers	create, get, update, delete
client.transfers	create, get
client.balances	get
client.forex	getRates
client.cardMetadata	get
client.networkTokens	provision, get, requestCryptogram, delete
client.accountUpdater	getUpdatedCredentials
client.applePay	generateCSR, uploadCertificate, enrollDomain
client.googlePay	enrollEntity, registerDomain, getRegisteredDomains, getEnrollmentState
client.forward	sendRequest, getRequest, createSecret, listSecrets, updateSecret, deleteSecret
client.sessions	create, get, update, complete, update3DSMethodCompletion
client.compliance	get, respond
client.agenticCommerce	createDelegatedToken
client.reports	list, get, getFile
client.financialActions	list
client.disputes	list, get, accept, provideEvidence, getEvidence, submitEvidence, submitArbitrationEvidence, getSubmittedArbitrationEvidence, getSubmittedEvidence, getSchemeFiles, uploadFile, getFile
client.workflows	list, create, get, patch, delete, addAction, updateAction, removeAction, addCondition, updateCondition, removeCondition, test, getEventTypes, getEvent, getActionInvocations, getSubjectEvents, reflowByEvent, reflowByEventAndWorkflow, reflow, reflowBySubject, reflowBySubjectAndWorkflow
client.cardholders	create, get, update, listCards
client.cardholderAccessTokens	request
client.cards	create, get, update, getCredentials, activate, suspend, revoke, renew, scheduleRevocation, deleteScheduledRevocation, enrol3DS, get3DSEnrollment, update3DSEnrollment
client.controls	create, listByTarget, get, update, delete
client.controlProfiles	create, list, get, update, delete, addTarget, removeTarget
client.controlGroups	create, listByTarget, get, delete
client.issuingTransactions	list, get
client.issuingDisputes	create, get, cancel, escalate
client.issuingSandbox	simulateAuthorization, simulateIncrementalAuthorization, simulateClearing, simulateRefund, simulateReversal
client.platformEntities	onboard, get, update, uploadFile, getFile, listMembers, reinviteMember
client.platformInstruments	add, get, update, list
client.payoutSchedules	get, update
client.reserveRules	add, get, update, list
client.identityApplicants	create, get, update, anonymize
client.identityVerification	createAndStart, create, get, anonymize, createAttempt, listAttempts, getAttempt, getReport
client.amlScreening	create, get
client.faceAuth	create, get, anonymize, createAttempt, listAttempts, getAttempt
client.idDocuments	create, get, anonymize, createAttempt, listAttempts, getAttempt, getReport

---

Testing

npm test              # vitest run
npm run test:watch    # vitest watch mode
npm run test:coverage # coverage report

All 68 tests use mock fetch — no live API calls, no credentials needed.

---

Building

npm run build   # ESM + CJS + type declarations
npm run clean   # remove dist/

---

License

MIT — see LICENSE.