Node Interfaces

AustralianPayslipV2

Interface

AustralianV2IssuanceInput

Interface

issuedAt

Property

issuedAt: string

key

Property

key: Buffer

payslipNonPii

Property

payslipNonPii: AustralianPayslipV2

pii

Property

pii: { accountName?: string; accountNumber?: string; address?: { lines?: string[]; postcode?: string; stateOrTerritory?: string; suburb?: string }; bsb?: string; department?: string; employeeName?: string; employerAbn?: string; employerName?: string; position?: string }

verifiablReference

Property

verifiablReference: string

BarcodeParts

Interface

encryptedPii

Property

AES-256-GCM ciphertext bytes.

encryptedPii: Uint8Array

verifiablReference

Property

Provider-generated reference, or one returned by client.registerNonPii.

verifiablReference: string

BarcodePngOptions

Interface

PNG-specific options. A superset of the SVG options, so callers can pass either.

compressionLevel

Property

DEFLATE level (0-9, default 6). Lossless at every level; only trades file size for encode speed.

compressionLevel: number

palette

Property

Deprecated. The compositor always emits the smallest lossless encoding (an 8-bit palette PNG; truecolour only if the palette ever overflows). This flag is ignored and will be removed in a future release.

palette: boolean

BarcodePngResult

Interface

content

Property

The exact string encoded in the QR code.

content: string

degraded

Property

True when the ladder traded scan robustness to fit the payload.

degraded: boolean

errorCorrectionLevel

Property

Error-correction level actually used (see BarcodeSvgResult).

errorCorrectionLevel: BarcodeErrorCorrectionLevel

height

Property

height: number

modulePx

Property

Rendered size of one QR module, in output pixels.

modulePx: number

png

Property

PNG image bytes.

png: Buffer

qrVersion

Property

QR symbol version (1-40), for scanner-fixture attribution.

qrVersion: number

width

Property

width: number

BarcodeSvgOptions

Interface

Branded “Secured by Verifiabl” barcode renderer.

The QR matrix comes from the qrcode library. Data modules are rendered as standard square modules, with rounded finder patterns in the three large corner sections.

environment

Property

API environment for the public QR scan URL. Defaults to “production”.

environment: VerifiablEnvironment

layout

Property

Badge arrangement (default “vertical”). “vertical” puts the navy “Secured by Verifiabl” header above the QR code. “horizontal” puts a light-tinted “Secured by Verifiabl” frame to the right of the QR code, for short, wide spaces.

layout: BarcodeLayout

maxErrorCorrection

Property

Highest QR error-correction level to use. The renderer still steps below this only when the payload would not otherwise fit the fixed frame.

Default “M” (~15% damage recovery) keeps the modules large and the symbol visually clean. Choose “Q” (~25% recovery) for documents expected to take heavy print wear, accepting a denser code (one or two QR versions larger).

maxErrorCorrection: "Q" | "M"

scanBaseUrl

Property

Advanced override for the public QR scan URL origin. Defaults to the selected environment’s scan URL origin. Must use https.

scanBaseUrl: string

width

Property

Total badge width in SVG user units / px. The default is the minimum: 480 for the vertical layout and 940 for the horizontal layout. Both minimums render the QR code at the same size.

width: number

BarcodeSvgResult

Interface

content

Property

The exact string encoded in the QR code.

content: string

degraded

Property

True when the ladder had to trade scan robustness to fit the payload (error correction below the configured ceiling, or modules below the ideal size). False for essentially all real records. Log this to observe the long tail at scale.

degraded: boolean

errorCorrectionLevel

Property

Error-correction level actually used. Normally the configured ceiling (maxErrorCorrection, default “M”); drops below it only for unusually long PII so the code still fits the fixed frame.

errorCorrectionLevel: BarcodeErrorCorrectionLevel

height

Property

height: number

modulePx

Property

Rendered size of one QR module, in output pixels.

modulePx: number

qrVersion

Property

QR symbol version (1-40), for scanner-fixture attribution.

qrVersion: number

svg

Property

Complete standalone SVG document.

svg: string

width

Property

width: number

BatchRecordResult

Interface

Per-record outcome, in the same order as the input records (so results[i] is the outcome of records[i]). code and detail accompany an “error” status. One bad record never fails the whole batch. Correlate by position, by the record’s externalId (echoed when supplied), or by verifiablReference.

code

Property

code: VerifiablErrorCode

detail

Property

detail: string

externalId

Property

Echoed back when the record supplied one.

externalId: string

status

Property

status: BatchRecordStatus

verifiablReference

Property

verifiablReference: string

EncryptedPii

Interface

encryptedPii

Property

AES-256-GCM ciphertext bytes to store or pass to the barcode and client APIs.

encryptedPii: Uint8Array

encryptionMetadata

Property

Server-side decryption metadata for registration endpoints.

encryptionMetadata: { iv: Uint8Array<ArrayBuffer>; tag: Uint8Array<ArrayBuffer> }

NewZealandPayslipV2

Interface

NewZealandV2IssuanceInput

Interface

issuedAt

Property

issuedAt: string

key

Property

key: Buffer

payslipNonPii

Property

payslipNonPii: NewZealandPayslipV2

pii

Property

pii: { accountName?: string; accountNumber?: string; address?: { city?: string; lines?: string[]; postcode?: string; suburb?: string }; department?: string; employeeName?: string; employerName?: string; irdNumber?: string; position?: string }

verifiablReference

Property

verifiablReference: string

PiiFieldViolation

Interface

A supplied PII field a formatter refused to encode, and why.

field

Property

Input field name, or a structured address path such as address.lines[0].

field: PiiFieldName | "address.suburb" | "address.stateOrTerritory" | "address.postcode" | "address.city" | templateLiteral

reason

Property

reason: PiiFieldViolationReason

PreparedV2Payslip

Interface

apiManagedRegistration

Property

API-managed issuance has no caller reference and cannot safely retry ambiguous failures.

apiManagedRegistration: { encryptedPii: Uint8Array<ArrayBuffer>; encryptionMetadata: { iv: Uint8Array<ArrayBuffer>; tag: Uint8Array<ArrayBuffer> }; issuedAt: string; payslipNonPii: { annualRateCents?: number; currency: "AUD" | "CAD" | "CHF" | "EUR" | "GBP" | "HKD" | "NZD" | "SGD" | "USD" | "ZAR"; deductions?: { amountCents: number; type: "union_professional_fees" | "workplace_giving" | "child_support_deduction" | "child_support_garnishee" | "other_post_tax" }[]; earnings?: ({ amountCents: number; leaveType: "cash_out_in_service" | "unused_on_termination" | "paid_parental" | "workers_compensation" | "ancillary_defence" | "other_paid_leave"; rateCents?: number; type: "paid_leave"; units?: number } | { allowanceType: "cents_per_km" | "award_transport" | "laundry" | "overtime_meal" | "travel" | "tools" | "tasks" | "qualifications" | "other"; amountCents: number; otherCategory?: "home_office" | "non_deductible" | "transport_fares" | "uniform" | "private_vehicle" | "general"; rateCents?: number; type: "allowance"; units?: number } | { amountCents: number; rateCents?: number; type: "ordinary" | "overtime" | "bonus_commission" | "directors_fees" | "lump_sum" | "return_to_work"; units?: number })[]; employmentBasis?: "full_time" | "part_time" | "casual" | "labour_hire" | "voluntary_agreement" | "death_beneficiary" | "non_employee"; engagementType?: "permanent" | "fixed_term"; grossCents: number; hourly?: { amountCents: number; hours: number; ordinaryRateCents: number }; netCents: number; payFrequency?: "weekly" | "fortnightly" | "monthly" | "quarterly"; paygwCents: number; paymentDate: string; periodEnd: string; periodStart: string; reimbursementsCents?: number; salarySacrifice?: { amountCents: number; type: "other" | "super" }[]; stslWithholdingCents?: number; superannuation?: { amountCents: number; contributionType: "superannuation_guarantee" | "resc" | "salary_sacrifice"; fundAbn?: string; usi?: string }[]; taxableGrossCents?: number; ytd?: { nonTaxableCents?: number; postTaxDeductionsCents?: number; reimbursementsCents?: number; superCents?: number; taxableCents?: number }; ytdGrossCents: number; ytdPaygwCents: number }; schema: "au.payslip.v1" } | { encryptedPii: Uint8Array<ArrayBuffer>; encryptionMetadata: { iv: Uint8Array<ArrayBuffer>; tag: Uint8Array<ArrayBuffer> }; issuedAt: string; payslipNonPii: AustralianPayslipV2; schema: "au.payslip.v2" } | { encryptedPii: Uint8Array<ArrayBuffer>; encryptionMetadata: { iv: Uint8Array<ArrayBuffer>; tag: Uint8Array<ArrayBuffer> }; issuedAt: string; payslipNonPii: NewZealandPayslipV2; schema: "nz.payslip.v2" }

registration

Property

registration: { encryptionMetadata: { iv: Uint8Array<ArrayBuffer>; tag: Uint8Array<ArrayBuffer> }; issuedAt: string; payslipNonPii: { annualRateCents?: number; currency: "AUD" | "CAD" | "CHF" | "EUR" | "GBP" | "HKD" | "NZD" | "SGD" | "USD" | "ZAR"; deductions?: { amountCents: number; type: "union_professional_fees" | "workplace_giving" | "child_support_deduction" | "child_support_garnishee" | "other_post_tax" }[]; earnings?: ({ amountCents: number; leaveType: "cash_out_in_service" | "unused_on_termination" | "paid_parental" | "workers_compensation" | "ancillary_defence" | "other_paid_leave"; rateCents?: number; type: "paid_leave"; units?: number } | { allowanceType: "cents_per_km" | "award_transport" | "laundry" | "overtime_meal" | "travel" | "tools" | "tasks" | "qualifications" | "other"; amountCents: number; otherCategory?: "home_office" | "non_deductible" | "transport_fares" | "uniform" | "private_vehicle" | "general"; rateCents?: number; type: "allowance"; units?: number } | { amountCents: number; rateCents?: number; type: "ordinary" | "overtime" | "bonus_commission" | "directors_fees" | "lump_sum" | "return_to_work"; units?: number })[]; employmentBasis?: "full_time" | "part_time" | "casual" | "labour_hire" | "voluntary_agreement" | "death_beneficiary" | "non_employee"; engagementType?: "permanent" | "fixed_term"; grossCents: number; hourly?: { amountCents: number; hours: number; ordinaryRateCents: number }; netCents: number; payFrequency?: "weekly" | "fortnightly" | "monthly" | "quarterly"; paygwCents: number; paymentDate: string; periodEnd: string; periodStart: string; reimbursementsCents?: number; salarySacrifice?: { amountCents: number; type: "other" | "super" }[]; stslWithholdingCents?: number; superannuation?: { amountCents: number; contributionType: "superannuation_guarantee" | "resc" | "salary_sacrifice"; fundAbn?: string; usi?: string }[]; taxableGrossCents?: number; ytd?: { nonTaxableCents?: number; postTaxDeductionsCents?: number; reimbursementsCents?: number; superCents?: number; taxableCents?: number }; ytdGrossCents: number; ytdPaygwCents: number }; schema: "au.payslip.v1"; verifiablReference?: string } | { encryptionMetadata: { iv: Uint8Array<ArrayBuffer>; tag: Uint8Array<ArrayBuffer> }; issuedAt: string; payslipNonPii: AustralianPayslipV2; schema: "au.payslip.v2"; verifiablReference?: string } | { encryptionMetadata: { iv: Uint8Array<ArrayBuffer>; tag: Uint8Array<ArrayBuffer> }; issuedAt: string; payslipNonPii: NewZealandPayslipV2; schema: "nz.payslip.v2"; verifiablReference?: string }

verifiablReference

Property

Persist this reference with the registration for cross-process self-managed retries.

verifiablReference: string

barcodeParts

Method

barcodeParts(reference: string) => BarcodeParts

Use the reference returned by registration (or the batch result).

Parameter	Type	Description
reference	string

Returns: BarcodeParts

QrCapacityErrorDetail

Interface

What the renderer was asked for when it ran out of capacity.

badgeWidth

Property

Badge width attempted, in SVG user units (SVG) or pixels (PNG).

badgeWidth: number

contentLength

Property

Length of the QR content (the scan URL) in characters.

contentLength: number

reason

Property

reason: QrCapacityFailureReason

RegisterNonPiiBatchResponse

Interface

results

Property

results: BatchRecordResult[]

ScanUrlOptions

Interface

environment

Property

API environment for the public QR scan URL. Defaults to “production”.

environment: VerifiablEnvironment

scanBaseUrl

Property

Advanced override for the public QR scan URL origin. Defaults to the selected environment’s scan URL origin. Must use https. This URL is printed on payslip documents and cannot be changed after issuance.

scanBaseUrl: string

VerifiablAuth

Interface

How the client authenticates to the Verifiabl API.

Pass the OAuth2 clientId/clientSecret issued during onboarding and the client fetches, caches, and refreshes access tokens automatically.

clientId

Property

OAuth client id issued by Verifiabl during onboarding.

clientId: string

clientSecret

Property

OAuth client secret. Load from a secrets manager; never hard-code it.

clientSecret: string

tokenUrl

Property

OAuth token endpoint (default: the environment’s auth service, e.g. https://auth.verifiabl.io/oauth/token). Overrides must use a Verifiabl auth host, or localhost for local development.

tokenUrl: string

VerifiablClientOptions

Interface

auth

Property

How to authenticate. See VerifiablAuth.

auth: VerifiablAuth

environment

Property

API environment. Defaults to “production”.

environment: VerifiablEnvironment

fetch

Property

Custom fetch implementation (for testing or instrumentation).

fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>

issuerBaseUrl

Property

Advanced local development override for issuer API calls (registerNonPii, registerNonPiiBatch, and registerAndBuildBarcode). Most integrations should leave this unset and use environment instead. Must use https, except localhost may use http.

issuerBaseUrl: string

maxRetries

Property

Maximum automatic retries after the first attempt (default: 2). Retries use exponential backoff with jitter and honour Retry-After. Registration calls carry client-generated references and retry 429, 408, 5xx, and network faults. registerAndBuildBarcode retries only 429 because its server-generated reference cannot deduplicate an ambiguous replay.

maxRetries: number

onError

Property

Called when an issuer API request fails before receiving a response.

onError: (event: VerifiablErrorEvent) => void

onRequest

Property

Called before each Verifiabl API request. Bodies are not included.

onRequest: (event: VerifiablRequestEvent) => void

onResponse

Property

Called after each Verifiabl API response. Bodies are not included.

onResponse: (event: VerifiablResponseEvent) => void

timeoutMs

Property

Request timeout in milliseconds (default: 30000).

timeoutMs: number

VerifiablErrorEvent

Interface

elapsedMs

Property

elapsedMs: number

error

Property

error: unknown

VerifiablRequestEvent

Interface

method

Property

method: "POST"

path

Property

path: string

url

Property

url: string

VerifiablRequestOptions

Interface

signal

Property

Abort signal for this request.

signal: AbortSignal

timeoutMs

Property

Request timeout in milliseconds. Defaults to the client’s timeoutMs.

timeoutMs: number

VerifiablResponseEvent

Interface

elapsedMs

Property

elapsedMs: number

requestId

Property

requestId: string | undefined

status

Property

status: number