Xendit Node.js SDK

Common errors

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

  cause 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

  cause 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.

  cause 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

  cause 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';`

Warnings

• breaking The `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.
• breaking The `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`.
• breaking The `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.
• gotcha The 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.
• gotcha The `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.

Install

• npm install xendit-node npm
• yarn add xendit-node yarn
• pnpm add xendit-node pnpm

Imports

• Xendit
  wrong:

  const Xendit = require('xendit-node')

  correct:

  import { Xendit } from '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
  wrong:

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

  correct:

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

  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
  wrong:

  import { Invoice } from 'xendit-node'

  correct:

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

  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.

Quickstart

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();