@thiagoprazeres/parse-e2eid

Parse and validate Brazilian Pix endToEndId — semantic date validation included, zero runtime dependencies.

Install

npm install @thiagoprazeres/parse-e2eid

Usage

import { parseE2EId, isValidE2EId } from '@thiagoprazeres/parse-e2eid';

parseE2EId('E6074694820230615143012345678901');
// {
//   ispb: '60746948',
//   initiatedAt: Date('2023-06-15T14:30:00.000Z'),
//   suffix: '12345678901'
// }

isValidE2EId('E6074694820230615143012345678901'); // → true
isValidE2EId('invalid');                          // → false
isValidE2EId('E6074694820230231143012345678901'); // → false  (Feb 31 doesn't exist)
isValidE2EId('E6074694820230229143012345678901'); // → false  (not a leap year)

API

parseE2EId(e2eId: string): ParsedE2EId

Parses the endToEndId string. Throws Error on:

• invalid format (wrong length, wrong prefix, non-digit ISPB)
• impossible date/time values (month 13, day 32, Feb 31, Feb 29 on non-leap years, hour 25, minute 60…)

interface ParsedE2EId {
  ispb: string;       // 8-digit initiating institution ISPB
  initiatedAt: Date;  // UTC timestamp
  suffix: string;     // 11-char unique suffix
}

isValidE2EId(e2eId: string): boolean

Returns true if the string is a structurally and semantically valid endToEndId. Never throws.

Format

E  {ISPB — 8 digits}  {YYYY MM DD}  {HH mm}  {11 alphanumeric chars}

Total length: 32 characters.

JavaScript's Date constructor silently overflows invalid dates (Feb 31 becomes Mar 3). This package validates every component explicitly — impossible dates are rejected with a descriptive error message.

Motivation

The standard BACEN endToEndId appears in bank statements, Pix receipts, and conciliation APIs. Parsing it reliably — including rejecting impossible dates that JavaScript's Date would silently normalize — is a recurring need in fintech backends and was not available as a standalone, zero-dependency package.

Scope

• Parses the ISPB, timestamp, and suffix from a Pix endToEndId
• Validates format (length, prefix, character set)
• Validates date/time semantics (no silent overflow)

Out of scope

• Does not enrich with institution name (see @thiagoprazeres/ispb-participants)
• Does not validate whether the ISPB exists in the SPI participant list
• Does not make any network requests
• Does not validate dynamic Pix endToEndIds (same format, different use case)

References

• BACEN Pix specification
• Manual de Padrões para Iniciação do Pix (BACEN)

License

Apache 2.0