{"id":12687,"library":"xendit-node","title":"Xendit Node.js SDK","description":"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.","status":"active","version":"7.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/xendit/xendit-node","tags":["javascript","typescript"],"install":[{"cmd":"npm install xendit-node","lang":"bash","label":"npm"},{"cmd":"yarn add xendit-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add xendit-node","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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+.","wrong":"const Xendit = require('xendit-node')","symbol":"Xendit","correct":"import { Xendit } from 'xendit-node'"},{"note":"The primary class to instantiate is `Xendit`, not `XenditClient`. All API methods are accessed via the `xenditClient` instance (e.g., `xenditClient.Invoice.createInvoice`).","wrong":"const xenditClient = new XenditClient({ /* ... */ })","symbol":"XenditClient","correct":"import { Xendit } from 'xendit-node'; const xenditClient = new Xendit({ /* ... */ });"},{"note":"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.","wrong":"import { Invoice } from 'xendit-node'","symbol":"Invoice and other API modules","correct":"import { Xendit } from 'xendit-node'; // Access via client instance: xenditClient.Invoice.createInvoice"}],"quickstart":{"code":"import { Xendit } from 'xendit-node';\n\nconst SECRET_API_KEY = process.env.XENDIT_SECRET_KEY ?? '';\n\nif (!SECRET_API_KEY) {\n  console.error(\"XENDIT_SECRET_KEY environment variable is not set.\");\n  process.exit(1);\n}\n\nconst xenditClient = new Xendit({\n  secretKey: SECRET_API_KEY,\n});\n\nasync function createAndGetInvoice() {\n  try {\n    const externalId = `invoice-${Date.now()}`;\n    const amount = 10000;\n\n    const createInvoicePayload = {\n      external_id: externalId,\n      amount: amount,\n      payer_email: 'test@example.com',\n      description: 'Test Invoice for Node.js SDK',\n      invoice_duration: 86400, // Required as number since v7.0.0\n      callback_url: 'https://your-callback-url.com/xendit-webhook'\n    };\n\n    console.log(`Creating invoice with external ID: ${externalId}...`);\n    const invoice = await xenditClient.Invoice.createInvoice(createInvoicePayload);\n    console.log('Invoice created successfully:', invoice);\n\n    console.log(`Getting invoice with ID: ${invoice.id}...`);\n    const retrievedInvoice = await xenditClient.Invoice.getInvoiceById({ id: invoice.id });\n    console.log('Invoice retrieved successfully:', retrievedInvoice);\n\n    // Example of accessing another service (e.g., Balance)\n    const balance = await xenditClient.Balance.getBalance({});\n    console.log('Current balance:', balance.balance);\n\n  } catch (error) {\n    if (error instanceof Error) {\n      console.error('Error interacting with Xendit API:', error.message);\n    } else {\n      console.error('An unknown error occurred:', error);\n    }\n  }\n}\n\ncreateAndGetInvoice();","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure that `invoice_duration` is always passed as a `number` (representing seconds) when creating invoices. Update your payload objects accordingly.","message":"The `invoice_duration` field in `CreateInvoiceAPI` has changed its type from `string` to `number`.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"If processing refund callbacks, update your code to reference `payment_id` instead of `payment_request_id`.","message":"The `payment_request_id` field in `RefundCallbackData` was renamed to `payment_id`.","severity":"breaking","affected_versions":">=4.2.0"},{"fix":"Ensure your code expects the `failure_code` in Payment Callbacks to be a string type.","message":"The `failure_code` field type in `PaymentCallback` was fixed to `String` (it might have been inferred incorrectly before).","severity":"breaking","affected_versions":">=4.1.0"},{"fix":"Upgrade your Node.js environment to version 18.0.0 or higher to ensure compatibility and leverage modern JavaScript features.","message":"The SDK requires Node.js version 18.0.0 or later. Using older Node.js versions may lead to runtime errors or unexpected behavior.","severity":"gotcha","affected_versions":"<18.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `secretKey` is a non-empty string when initializing `new Xendit({ secretKey: 'YOUR_SECRET_KEY' })`.","cause":"The Xendit client was not instantiated with a valid `secretKey`, or `secretKey` was undefined/null.","error":"TypeError: Cannot read properties of undefined (reading 'createInvoice')"},{"fix":"Convert `invoice_duration` to a `number` type. For example, `invoice_duration: 86400` instead of `invoice_duration: '86400'`.","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.","error":"Error: \"invoice_duration\" must be a number"},{"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.","cause":"The package `xendit-node` is not installed, or the import path is incorrect, or TypeScript cannot find its type definitions.","error":"Error: Cannot find module 'xendit-node' or its corresponding type declarations."},{"fix":"Use the correct ESM named import: `import { Xendit } from 'xendit-node';`","cause":"Attempting to instantiate `Xendit` using CommonJS `require` syntax or `import Xendit from 'xendit-node'` (default import) when the package expects a named import.","error":"TypeError: Xendit is not a constructor"}],"ecosystem":"npm"}