PII and encryption

PII serialisation format

For AU/NZ v2 payslips, use the jurisdiction-specific SDK preparation helper by default. It selects the PII format and schema, then encrypts locally. If you use the low-level APIs, put PII in a pipe-delimited string before encryption. Use the format that matches the record’s jurisdiction:

• For au.payslip.v2, use AU2.
• For nz.payslip.v2, use NZ2.

Each format has 8 fields in a fixed sequence. Start the string with the format name and a pipe. Then add the 8 fields, with a pipe between each field. If a field has no value, keep the pipe and send an empty field. Then the position of each field stays the same. All fields are optional.

Send each value as the payslip shows it. Do not remove masks, spaces or hyphens.

AU2

AU2: all fields populated

AU2|Jane A. Doe|Senior Developer|Engineering|12 345 678 901|062-000|****5678|Jane A Doe|12 Example St, Sydney NSW 2000

AU2: some fields omitted

AU2|Jane A. Doe|||Example Payroll Pty Ltd|062-000|****5678||

#	Field	Example
1	employee_name	Jane A. Doe
2	position	Senior Developer
3	department	Engineering
4	employer_identity	12 345 678 901
5	bsb	062-000
6	account_number	****5678
7	account_name	Jane A Doe
8	address	12 Example St, Sydney NSW 2000

For employer_identity, send the employer ABN. If the payslip shows no ABN, send the employer name.

NZ2

NZ2: all fields populated

NZ2|Aroha Smith|123-456-789|Nurse|Ward 4|Example Health Limited|12-3456-0123456-00|A Smith|1 Example Road, Te Aro, Wellington 6011

#	Field	Example
1	employee_name	Aroha Smith
2	ird_number	123-456-789
3	position	Nurse
4	department	Ward 4
5	employer_name	Example Health Limited
6	account_number	12-3456-0123456-00
7	account_name	A Smith
8	address	1 Example Road, Te Aro, Wellington 6011

Rules for AU2 and NZ2

• Encode the complete string as UTF-8. Keep it at 1,024 bytes or less.
• Fields must not contain |, control or formatting characters, or line or paragraph separators.
• Put the address on one line.

AU2 and NZ2 use the character rules of the machine-readable P2 text profile. The profile also gives test vectors.

The SDKs make these fields for you:

• Give the address in parts. The SDKs join the parts into one address field.
• Give the employer name and the employer ABN. The AU2 formatter writes the ABN if it is present, and the name if not.

P2

Verifiabl also reads P2, the earlier format, for all schemas. P2 has the same 8 fields as AU2, but field 4 is the employer ABN as 11 digits without separators. Use AU2 or NZ2 for new payslips.

Encryption

Encrypt the PII with AES-256-GCM (Galois/Counter Mode) and a 256-bit symmetric key. The fields below are the encryption metadata. Send this metadata with each registration.

Your encryption key

The 256-bit key belongs to your payroll company. Each payroll provider has a separate key, and you receive yours during onboarding.

One key encrypts and decrypts. You encrypt the PII with the key on your own infrastructure. The verification service holds a copy of the key, and decrypts the PII with it during a lender verification. The registration service holds no key.

The SDK examples read the raw key bytes from VERIFIABL_ENCRYPTION_KEY_BASE64.

Encryption metadata fields

Field	Value	Encoding
iv	96-bit initialisation vector (nonce)	base64url
tag	128-bit authentication tag	base64url

Encode ciphertext, IV and tag as unpadded base64url, not standard base64. Use your platform’s base64url encoder; the SDKs handle this automatically.

A new IV for each record

Make a new random 96-bit IV for each record. Use a secure random source for the 12 bytes. Use each IV for one record only. Do not use a fixed IV.

The SDKs generate a fresh IV for every encryption. Reuse returns 409 IV_REUSED for a single registration or an error for that record in a batch. Encrypt the record again and rebuild its barcode before retrying.

An idempotent replay does not return IV_REUSED. If you send the same verifiabl_reference with the same content, the API returns the idempotent result. Refer to Idempotency and retries.

Key rotation

Verifiabl rotates your key at intervals. A rotation has no effect on the payslips that you issued before it. During verification, Verifiabl tests each of your active keys against the GCM authentication tag, so a lender can still verify a payslip with the key that encrypted it.

The cURL examples target sandbox and use placeholder encryption values. Replace every placeholder and example reference before registering real data.