Skip to content
Verifiabl
Demo

Node Classes

PiiValidationError

Section titled “PiiValidationError”

Class

Thrown by formatPii, formatAustralianPii and formatNewZealandPii when a field value cannot be encoded in the PII wire format. The pipe is the field delimiter and the format has no escape mechanism, so an offending value must be corrected at the source (strip the character) rather than escaped. violations names each field and reason so callers can guide the user without echoing the value, which is PII.

constructor

Section titled “constructor”

Constructor

PiiValidationError(violations: readonly PiiFieldViolation[]) => PiiValidationError
Parameter Type Description
violations readonly PiiFieldViolation[]

Returns: PiiValidationError

violations

Section titled “violations”

Property

violations: readonly PiiFieldViolation[]

QrCapacityError

Section titled “QrCapacityError”

Class

Thrown by createBarcodeSvg and createBarcodePng when the QR content does not fit. The PII behind it is caller-supplied, so this is rejected input rather than a renderer fault: catch it to report the length back to the caller instead of failing the surrounding operation.

constructor

Section titled “constructor”

Constructor

QrCapacityError(detail: QrCapacityErrorDetail) => QrCapacityError
Parameter Type Description
detail QrCapacityErrorDetail

Returns: QrCapacityError

badgeWidth

Section titled “badgeWidth”

Property

badgeWidth: number

contentLength

Section titled “contentLength”

Property

contentLength: number

reason

Section titled “reason”

Property

reason: QrCapacityFailureReason

VerifiablApiError

Section titled “VerifiablApiError”

Class

Error thrown for any non-2xx Verifiabl API response. Match on code (stable) rather than message (may change).

code is “INTERNAL_ERROR” when the response carried no parseable Verifiabl error body (e.g. a gateway error page); check status for the raw HTTP status in that case.

constructor

Section titled “constructor”

Constructor

VerifiablApiError(status: number, body: { code: string; detail?: string; error: string; fieldErrors?: { message: string; path: string }[] } | undefined, requestId?: string) => VerifiablApiError
Parameter Type Description
status number
body { code: string; detail?: string; error: string; fieldErrors?: { message: string; path: string }[] } | undefined
requestId string

Returns: VerifiablApiError

body

Section titled “body”

Property

body: { code: string; detail?: string; error: string; fieldErrors?: { message: string; path: string }[] } | undefined

code

Section titled “code”

Property

code: VerifiablErrorCode

requestId

Section titled “requestId”

Property

requestId: string | undefined

status

Section titled “status”

Property

status: number

VerifiablAuthError

Section titled “VerifiablAuthError”

Class

Error thrown when an OAuth access token cannot be obtained. status is the HTTP status returned by the token endpoint, or undefined when the request itself failed or the response was unparseable.

constructor

Section titled “constructor”

Constructor

VerifiablAuthError(message: string, status?: number) => VerifiablAuthError
Parameter Type Description
message string
status number

Returns: VerifiablAuthError

status

Section titled “status”

Property

status: number | undefined

VerifiablClient

Section titled “VerifiablClient”

Class

Minimal typed client for the Verifiabl API. Uses native fetch with no runtime HTTP dependencies. Requires Node.js 20+.

constructor

Section titled “constructor”

Constructor

VerifiablClient(options: VerifiablClientOptions) => VerifiablClient
Parameter Type Description
options VerifiablClientOptions

Returns: VerifiablClient

registerAndBuildBarcode

Section titled “registerAndBuildBarcode”

Method

registerAndBuildBarcode(request: { 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" }, options: VerifiablRequestOptions) => Promise<{ barcode: { data: string; format: "png" }; verifiablReference: string }>

Register non-PII payslip data and have the API build the barcode. Sends the encrypted PII alongside the non-PII data.

Throws VerifiablIvReuseError when the iv has already been registered by this issuer.

Parameter Type Description
request { 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" }
options VerifiablRequestOptions

Returns: Promise<{ barcode: { data: string; format: "png" }; verifiablReference: string }>

registerNonPii

Section titled “registerNonPii”

Method

registerNonPii(request: { 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 }, options: VerifiablRequestOptions) => Promise<{ verifiablReference: string }>

Register non-PII payslip data and decryption metadata. Returns the Verifiabl reference to embed in a locally generated barcode. The SDK generates and sends a reference when one is not supplied, making transient failures safe to retry. Supply and persist verifiablReference when retries must remain correlated across separate calls or process restarts.

Throws VerifiablIvReuseError when the iv has already been registered by this issuer.

Parameter Type Description
request { 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 }
options VerifiablRequestOptions

Returns: Promise<{ verifiablReference: string }>

registerNonPiiBatch

Section titled “registerNonPiiBatch”

Method

registerNonPiiBatch(request: { records: { encryptionMetadata: { iv: Uint8Array<ArrayBuffer>; tag: Uint8Array<ArrayBuffer> }; externalId?: string; issuedAt: string; payslipNonPii: unknown; schema: string; verifiablReference: string }[] }, options: VerifiablRequestOptions) => Promise<RegisterNonPiiBatchResponse>

Register a batch of non-PII payslip records in a single request, up to MAX_BATCH_RECORDS records. Each record carries a provider-generated Verifiabl reference (from generateVerifiablReference) and the same fields as registerNonPii. Results come back in the same order as the input records (results[i] is the outcome of records[i]); one bad record never fails the batch.

A record whose iv is already registered by this issuer, or repeated within this batch, comes back as an error result that isIvReuseResult matches.

Parameter Type Description
request { records: { encryptionMetadata: { iv: Uint8Array<ArrayBuffer>; tag: Uint8Array<ArrayBuffer> }; externalId?: string; issuedAt: string; payslipNonPii: unknown; schema: string; verifiablReference: string }[] }
options VerifiablRequestOptions

Returns: Promise<RegisterNonPiiBatchResponse>

VerifiablIvReuseError

Section titled “VerifiablIvReuseError”

Class

Thrown when the API rejects a registration because its encryptionMetadata.iv is already registered to your issuer. A subclass of VerifiablApiError, so existing handling still catches it.

Encrypt the payslip again with encryptPii to get a new iv, resend the record with the new encryption metadata, and rebuild any barcode that you rendered from the previous ciphertext. Resending the same request gives the same result.

constructor

Section titled “constructor”

Constructor

VerifiablIvReuseError(status: number, body: { code: string; detail?: string; error: string; fieldErrors?: { message: string; path: string }[] } | undefined, requestId?: string) => VerifiablIvReuseError
Parameter Type Description
status number
body { code: string; detail?: string; error: string; fieldErrors?: { message: string; path: string }[] } | undefined
requestId string

Returns: VerifiablIvReuseError