xendit-node

library7.0.0jsnpmunverified

The Xendit Node.js SDK, currently at version 7.0.0, provides an official, convenient, and type-safe interface for integrating Node.js applications with the Xendit REST API. It abstracts direct HTTP requests, offering a structured way to interact with Xendit's various payment and financial services, including invoicing, payment requests, refunds, and balance inquiries. The SDK ships with first-class TypeScript support, enhancing developer experience through strong typing and autocompletion. It requires Node.js 18.0 or later for execution. While specific release cadence for major versions isn't explicitly stated, minor and patch versions are released regularly to add new features, support new payment channels, and fix bugs. A key differentiator is its direct support from Xendit, ensuring up-to-date API coverage and adherence to best practices for secure and reliable payment processing in Southeast Asia.

payments http-networking

npm install xendit-node

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · XENDIT-NODE

xendit-node

paymentsjavascriptv7.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Xendit

✓ import { Xendit } from 'xendit-node'

✗ const Xendit = require('xendit-node')

The SDK primarily uses ESM named imports. While CommonJS `require` might work in some setups, direct named imports are the recommended and type-safe approach for Node.js 18+.

XenditClient

✓ import { Xendit } from 'xendit-node'; const xenditClient = new Xendit({ /* ... */ });

✗ const xenditClient = new XenditClient({ /* ... */ })

The primary class to instantiate is `Xendit`, not `XenditClient`. All API methods are accessed via the `xenditClient` instance (e.g., `xenditClient.Invoice.createInvoice`).

Invoice and other API modules

✓ import { Xendit } from 'xendit-node'; // Access via client instance: xenditClient.Invoice.createInvoice

✗ import { Invoice } from 'xendit-node'

API categories like `Invoice`, `PaymentRequest`, etc., are exposed as properties on the instantiated `Xendit` client, not as direct named exports from the top-level package.

This quickstart demonstrates how to initialize the Xendit client using an environment variable for the API key, create a new invoice, retrieve it by ID, and fetch the account balance.

import { Xendit } from 'xendit-node'; const SECRET_API_KEY = process.env.XENDIT_SECRET_KEY ?? ''; if (!SECRET_API_KEY) { console.error("XENDIT_SECRET_KEY environment variable is not set."); process.exit(1); } const xenditClient = new Xendit({ secretKey: SECRET_API_KEY, }); async function createAndGetInvoice() { try { const externalId = `invoice-${Date.now()}`; const amount = 10000; const createInvoicePayload = { external_id: externalId, amount: amount, payer_email: 'test@example.com', description: 'Test Invoice for Node.js SDK', invoice_duration: 86400, // Required as number since v7.0.0 callback_url: 'https://your-callback-url.com/xendit-webhook' }; console.log(`Creating invoice with external ID: ${externalId}...`); const invoice = await xenditClient.Invoice.createInvoice(createInvoicePayload); console.log('Invoice created successfully:', invoice); console.log(`Getting invoice with ID: ${invoice.id}...`); const retrievedInvoice = await xenditClient.Invoice.getInvoiceById({ id: invoice.id }); console.log('Invoice retrieved successfully:', retrievedInvoice); // Example of accessing another service (e.g., Balance) const balance = await xenditClient.Balance.getBalance({}); console.log('Current balance:', balance.balance); } catch (error) { if (error instanceof Error) { console.error('Error interacting with Xendit API:', error.message); } else { console.error('An unknown error occurred:', error); } } } createAndGetInvoice();

Debug

Known issues

breakingThe `invoice_duration` field in `CreateInvoiceAPI` has changed its type from `string` to `number`.

fix

Ensure that `invoice_duration` is always passed as a `number` (representing seconds) when creating invoices. Update your payload objects accordingly.

affects: >=7.0.0

breakingThe `payment_request_id` field in `RefundCallbackData` was renamed to `payment_id`.

fix

If processing refund callbacks, update your code to reference `payment_id` instead of `payment_request_id`.

affects: >=4.2.0

breakingThe `failure_code` field type in `PaymentCallback` was fixed to `String` (it might have been inferred incorrectly before).

fix

Ensure your code expects the `failure_code` in Payment Callbacks to be a string type.

affects: >=4.1.0

gotchaThe SDK requires Node.js version 18.0.0 or later. Using older Node.js versions may lead to runtime errors or unexpected behavior.

fix

Upgrade your Node.js environment to version 18.0.0 or higher to ensure compatibility and leverage modern JavaScript features.

affects: <18.0.0

gotchaThe `secretKey` for Xendit client instantiation must be your actual secret API key obtained from the Xendit Dashboard, not the publishable key. Never expose your secret key directly in client-side code.

fix

Store your `secretKey` securely, ideally as an environment variable (e.g., `process.env.XENDit_SECRET_KEY`) and load it at runtime. Access tokens should not be hardcoded.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'createInvoice')

The Xendit client was not instantiated with a valid `secretKey`, or `secretKey` was undefined/null.

fix

Ensure `secretKey` is a non-empty string when initializing `new Xendit({ secretKey: 'YOUR_SECRET_KEY' })`.

Error: "invoice_duration" must be a number

Since v7.0.0, the `invoice_duration` field for invoice creation expects a numeric value (in seconds) but received a string or other non-numeric type.

fix

Convert `invoice_duration` to a `number` type. For example, `invoice_duration: 86400` instead of `invoice_duration: '86400'`.

Error: Cannot find module 'xendit-node' or its corresponding type declarations.

The package `xendit-node` is not installed, or the import path is incorrect, or TypeScript cannot find its type definitions.

fix

Run `npm install xendit-node@latest` (or `yarn add xendit-node@latest`). Ensure your `tsconfig.json` includes `node_modules` in `typeRoots` if custom configurations are used.

TypeError: Xendit is not a constructor

Attempting to instantiate `Xendit` using CommonJS `require` syntax or `import Xendit from 'xendit-node'` (default import) when the package expects a named import.

fix

Use the correct ESM named import: `import { Xendit } from 'xendit-node';`

Upgrade

Version history

7.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

50 hits · last 30 days

node

Resources

githubhttps://github.com/xendit/xendit-node ↗

packagehttps://www.npmjs.com/package/xendit-node ↗

homepagehttps://xendit.co ↗