Culqi Node SDK (TypeScript)

Culqi, zero-runtime-dependency SDK for integrating Culqi’s REST API in Node.js projects.
The library ships with API v2 resources and is scaffolded to support future versions side by side.

Requirements

The SDK Supports NodeJS version 22 or higher.

Quick start

npm install culqi-nodejs

import { CulqiClient } from 'culqi-nodejs';

const culqi = CulqiClient.init({
  publicKey: process.env.CULQI_PUBLIC_KEY!,
  secretKey: process.env.CULQI_SECRET_KEY!,
  apiVersion: '2',
});

const { id: tokenId } = await culqi.tokens.create({
  card_number: '4111111111111111',
  cvv: '123',
  expiration_month: '07',
  expiration_year: '2027',
  email: '[email protected]',
});

await culqi.charges.create({
  amount: 1000,
  currency_code: 'PEN',
  source_id: tokenId,
  email: '[email protected]',
});

Scripts

| Command | Description | | ---------------- | ------------------------------------------ | | npm run build | Compile TypeScript to dist/ | | npm test | Run unit tests + coverage (Jest) | | npm test:e2e | Run E2E tests against Culqi sandbox¹ | | npm run lint | Lint codebase with ESLint v9 (Flat Config) | | npm run format | Format code with Prettier |

¹ Requires CULQI_PUBLIC_KEY and CULQI_SECRET_KEY environment variables.

Project structure

(high-level; paths may vary)

├─ src/
│  ├─ client/
│  │   ├─ culqi-client.ts
│  │   └─ http-client.ts
│  ├─ examples/
│  │   ├─ cards
│  │   ├─ charges
│  │   └─ ...
│  ├─ resources/
│  │   └─ v2/
│  │   │   ├─ cards.resource.spec.ts
│  │   │   ├─ cards.resource.ts
│  │   │   ├─ charges.resource.spec.ts
│  │   │   ├─ charges.resource.ts
│  │   │   └─ ...
│  │   ├─ base.resource.ts
│  ├─ types/
│  │   ├─ v2/
│  │   │   ├─ cards.ts
│  │   │   ├─ charges.ts
│  │   │   └─ ...
│  │   ├─ resource.ts
│  ├─ utils/
│  │   └─ resource-factory.ts
│  └─ index.ts
├─ tests/
│  ├─ resources/
│  │    └─ v2/
│  │        ├─ cards.e2e.spec.ts
│  │        ├─ charges.e2e.spec.ts
│  │        └─ ...
│  └─ e2e.config.ts
└─ ...

Available operations

Tokens

• Create token
• Get tokens
• Get token
• Update token
• Create token (Yape)

Charges

• Create charge
• Get charges
• Get charge
• Update charge
• Capture charge

Refunds

• Create refund
• Get refunds
• Get refund
• Update refund

Customers

• Create customer
• Get customers
• Get customer
• Update customer
• Delete customer

Cards

• Create card
• Get cards
• Get card
• Update card
• Delete card

Plans

• Create plan
• Get plans
• Get plan
• Update plan
• Delete plan

Subscriptions

• Create subscription
• Get subscriptions
• Get subscription
• Update subscription
• Cancel subscription

Orders

• Create order
• Get orders
• Confirm order
• Confirm order type
• Get order
• Update order
• Delete order

Events

• Get events
• Get event

Statements

• Get operations
• Get deposits
• Get deposit
• Get billings

Versioning strategy

• Code & Types are namespaced by API version (src/types/v2, src/resources/v2).
• If Culqi ever ships an API v3, we’ll simply add new types and resources inside a v3 namespace without breaking applications that remain on v2.

Sponsor this project

License

MIT © 2025 Francisco Luis Rios Vega