Kushki Node.js SDK: installation, setup and your first charges
Kushki's official Node.js SDK abstracts all API complexity. In this post we cover installation, error handling and testing with mocks.
February 20, 2026
·9 minKushki's official Node.js SDK provides complete TypeScript types, automatic retry handling with exponential backoff and helpers for API error parsing. If you're building in Node.js, it's the recommended starting point.
Installation
Install the SDK with npm or yarn. The package includes TypeScript types — you don't need to install @types/kushki separately.
Authentication
The SDK supports two modes: sandbox (for testing) and production. Never put your private key in code — use environment variables. The SDK reads KUSHKI_PRIVATE_KEY from the environment if you don't pass the key explicitly.
In production always use process.env for keys. Consider using a secrets manager like AWS Secrets Manager or GCP Secret Manager instead of plain environment variables.
Your first charge
The charges.create() method accepts a token (obtained with Kushki.js), the amount in cents and the ISO 4217 currency. It returns a promise with the transaction object or throws a KushkiError on failure.
Error handling
The SDK distinguishes between network errors (NetworkError), API errors (ApiError with code and message) and validation errors (ValidationError). Always handle all three types separately to give the user useful feedback.
- NetworkError: connectivity issue — retry with backoff
- ApiError code 402: insufficient funds — notify the user
- ApiError code 422: invalid data — review the payload
- ValidationError: SDK error itself — review the integration
Testing with mocks
The SDK exports KushkiMock for testing. You don't need a sandbox account for your unit tests — the mock simulates all API success and error cases without making real requests.