Skip to content
Verifiabl
Demo

Register payslips

This page describes the inputs and the results of preparing and registering payslips. For the steps, follow Make the QR code in your system.

Prepare a payslip

Section titled “Prepare a payslip”

Prepare each payslip with the helper for its country. The helper validates the non-PII data and encrypts the PII. It does not make a network call.

Country Schema Helper
Australia au.payslip.v2 prepareAustralianV2PayslipV2Issuance.PrepareAustralianprepare_australian_v2_payslip
New Zealand nz.payslip.v2 prepareNewZealandV2PayslipV2Issuance.PrepareNewZealandprepare_new_zealand_v2_payslip

One integration can use both helpers.

Each helper uses these inputs:

Input Name Description
PII piipiipii: The employee’s personal details. These values go only into the encrypted QR code.
Payslip data payslipNonPiipayslippayslip_non_pii: The non-PII payslip values. Refer to the Australian or the New Zealand payslip schema.
Issue time issuedAtissuedAtissued_at: The time that you issue the payslip.
Key keykeykey: Your 32-byte encryption key from the provider portal. Refer to Encryption.
Reference verifiablReferenceverifiablReferenceverifiabl_reference: Optional. If you do not set it, the helper makes a new reference.

The helper returns a prepared payslip:

Member Name Description
Reference verifiablReferenceVerifiablReferenceverifiabl_reference The reference for this payslip. It is the idempotency key for registration.
Registration registrationRegistrationregistration The registration request. It contains the reference, the non-PII data, the initialisation vector (IV) and the tag.
Barcode parts barcodeParts(reference)BarcodeParts(reference)barcode_parts(reference) The reference and the ciphertext for the QR code.

Payslip values

Section titled “Payslip values”
  • Amounts, rates and quantities are decimal strings, for example "1234.56". The SDK sends the string as you give it. It does not accept a JavaScript number.
  • Dates are YYYY-MM-DD strings.
  • Code lists such as australianPayFrequencies and newZealandLeaveBalanceUnits show the accepted codes.
  • Amounts, rates and quantities are decimal values. The SDK keeps the scale of the value. For example, it sends 1.50m as "1.50".
  • Dates are DateOnly on .NET 8 or newer, and YYYY-MM-DD strings on .NET Framework 4.7.2. The SDK rejects default(DateOnly).
  • Each code field has a constants class, for example AustralianPayFrequencies. Earnings lines have factory methods, for example AustralianPayslipV2EarningsItem.Ordinary.
  • Amounts, rates and quantities are decimal strings, for example "1234.56". The SDK rejects an Integer, a Float or a BigDecimal.
  • Dates are YYYY-MM-DD strings.
  • Verifiabl::Issuer::PayslipCodes has the accepted codes for each country. The SDK rejects fields that are not in the schema.

Currency is required. Use a current ISO 4217 code.

Register one payslip

Section titled “Register one payslip”

registerNonPiiRegisterNonPiiAsyncregister_non_pii returns the same result for a new record and for a record that you registered before with the same content.

Register a pay run

Section titled “Register a pay run”

Use registerNonPiiBatchRegisterNonPiiBatchAsyncregister_non_pii_batch to register a maximum of 1,000 records in one request. For a pay run of more than 1,000 records, send the batches one at a time.

Each record contains the prepared registration and an optional externalIdExternalIdexternal_id. The external ID is your identifier for the record. The API returns it in the result and does not store it.

The results are in the same sequence as the records that you sent. Each result has one of these statuses:

Status Description What to do
created The API registered the record. Make the QR code.
duplicate A record with the same reference and content exists already. Make the QR code.
error The API did not register the record. The result code tells you why. Use the result code.

An error in one record does not stop the other records. The SDK checks the payslip data of each record before it sends the batch. If a record fails this check, its result has the status error and the code VALIDATION_FAILED. The SDK does not send that record. If a reference, schema, issue time, IV, tag or external ID is not valid, the SDK throws ZodErrorArgumentExceptionArgumentError and sends no records.

If the call throws after all retries, refer to Retries and timeouts.