NPWP

Utilities for working with Indonesian Tax Identity Numbers (Nomor Pokok Wajib Pajak).

Overview

The NPWP module provides utilities to validate, format, parse, and mask Indonesian Tax Identity Numbers. It follows the official 15-digit format and handles both formatted (with dots and dashes) and unformatted input.

Features

Validation: Check if an NPWP is valid based on its length and basic structure.
Formatting: Format raw 15-digit NPWP into the standard 00.000.000.0-000.000 pattern.
Parsing: Extract information from NPWP like identity code, serial number, and office code.
Masking: Mask NPWP for privacy while optionally preserving its format.

Installation

npm


npm install @indodev/toolkit

pnpm


pnpm add @indodev/toolkit

yarn


yarn add @indodev/toolkit

bun


bun add @indodev/toolkit

Quick Start


import { validateNPWP, formatNPWP, parseNPWP, maskNPWP, cleanNPWP, isNIKBasedNPWP } from '@indodev/toolkit/npwp';
 
// Validate NPWP
validateNPWP('091234567012000'); // true
 
// Format NPWP
formatNPWP('091234567012000');
// '09.123.456.7-012.000'
 
// Parse NPWP
const info = parseNPWP('09.123.456.7-012.000');
console.log(info?.identityCode); // '09'
 
// Mask NPWP
maskNPWP('09.123.456.7-012.000');
// '09.123.***.*-012.000'
 
// Clean NPWP (remove non-digit characters)
cleanNPWP('01.234.567.8-012.345'); // '012345678012345'
 
// Check if NIK-based (16-digit format)
isNIKBasedNPWP('3201234567890003'); // true
isNIKBasedNPWP('091234567012000');  // false (15-digit)

API Reference

validateNPWP()

Validates an Indonesian NPWP string.

Type Signature:


function validateNPWP(npwp: string): boolean;

Parameters:

Name	Type	Description
`npwp`	`string`	The NPWP string to validate

Returns:

boolean - Returns true if valid, false otherwise.

formatNPWP()

Formats a 15-digit NPWP string into the standard 00.000.000.0-000.000 format.

Type Signature:


function formatNPWP(npwp: string): string;

Parameters:

Name	Type	Description
`npwp`	`string`	The 15-digit NPWP string

Returns:

string - Formatted NPWP string, or the original if invalid.

parseNPWP()

Parses an NPWP string and extracts its components.

Type Signature:


function parseNPWP(npwp: string): NPWPInfo | null;

Parameters:

Name	Type	Description
`npwp`	`string`	The NPWP string to parse

Returns:

NPWPInfo | null - Parsed NPWP information or null if invalid.

maskNPWP()

Masks an NPWP for privacy.

Type Signature:


function maskNPWP(npwp: string, options?: MaskOptions): string;

Parameters:

Name	Type	Description
`npwp`	`string`	The NPWP to mask
`options`	`MaskOptions`	Optional masking configuration

Returns:

string - Masked NPWP.

cleanNPWP()

Cleans an NPWP by removing all non-digit characters.

Type Signature:


function cleanNPWP(npwp: string): string;

Parameters:

Name	Type	Description
`npwp`	`string`	The NPWP to clean

Returns:

string - Cleaned NPWP (digits only).

Example:


cleanNPWP('01.234.567.8-012.345'); // '012345678012345'

isNIKBasedNPWP()

Checks if an NPWP is based on NIK (16-digit format).

Type Signature:


function isNIKBasedNPWP(npwp: string): boolean;

Parameters:

Name	Type	Description
`npwp`	`string`	The NPWP to check

Returns:

boolean - Returns true if NIK-based (16-digit), false otherwise.

Example:


isNIKBasedNPWP('3201234567890003'); // true
isNIKBasedNPWP('091234567012000');  // false

Type Reference

NPWPInfo


interface NPWPInfo {
  identityCode: string;
  serialNumber: string;
  checkDigit: string;
  officeCode: string;
  branchCode: string;
  formatted: string;
  isValid: boolean;
}

MaskOptions


interface MaskOptions {
  start?: number; // Digits visible at start (default: 5)
  end?: number; // Digits visible at end (default: 3)
  char?: string; // Mask character (default: '*')
  preserveFormat?: boolean; // Keep dots and dashes (default: true)
}

InvalidNPWPError

Error class for invalid NPWP with error code for programmatic handling.


class InvalidNPWPError extends Error {
  readonly code = 'INVALID_NPWP';
  constructor(message?: string);
}

Example:


import { InvalidNPWPError, validateNPWP } from '@indodev/toolkit/npwp';
 
try {
  if (!validateNPWP(npwp)) {
    throw new InvalidNPWPError('Invalid NPWP format');
  }
} catch (error) {
  if (error instanceof InvalidNPWPError) {
    console.log(error.code); // 'INVALID_NPWP'
  }
}