Use the Issuer API

Use the Issuer API to register payslip records. The generated Issuer API reference defines the exact HTTP contract.

Base URL

https://register.verifiabl.io

Use https://register.sandbox.verifiabl.io in sandbox.

Authentication

The Issuer API uses OAuth 2.0 client credentials. Exchange the client ID and client secret from your onboarding for a short-lived access token.

POST https://auth.verifiabl.io/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://register.verifiabl.io",
  "scope": "verifiabl:issuer"
}

Use https://auth.sandbox.verifiabl.io/oauth/token in sandbox. Set audience to https://register.sandbox.verifiabl.io.

Send the returned access token with each request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Cache the token until its expiry is near. After a 401, request a new token and retry once. Issuer API credentials do not give access to the Verifier API.

Select an operation

Use the operation that matches how you issue payslips:

Use registerNonPII to register one record. Build the QR code in your system.
Use registerNonPIIBatch to register up to 1,000 records for a pay run.
Use registerAndBuildBarcode if your system cannot build the QR code. The response contains a PNG badge.

The issuing guides show the complete workflow. For Australian and New Zealand v2 payslips, use the jurisdiction-specific SDK preparation helper by default. It selects the matching non-PII schema and PII format, validates with the SDK’s rules, and encrypts locally. It does not accept a caller-selected schema, formatted plaintext, or ciphertext. Keep employee PII out of non-PII fields. The helper cannot check that the input describes a real payslip. Use the low-level APIs for legacy formats or advanced integrations.

For au.payslip.v2 and nz.payslip.v2, send only the documented non-PII fields. The Node SDK uses typed inputs and validates field values before it sends a request. The .NET SDK uses typed payslip fields, and the Ruby SDK rejects unknown fields. The Issuer API validates the request in every case. Keep identifying details in the encrypted PII profile, not in the non-PII fields.

Handle errors

Each generated operation lists its status codes and error responses. Use code in conditional statements. Do not compare error or detail, because that text can change.

A validation response can contain field_errors. Use each path to find the applicable request field.

A batch request can return 200 when one or more records have an error. Examine the status and code of each result.

Idempotency and retries

Use a provider-generated verifiabl_reference for registerNonPII and registerNonPIIBatch. The reference is the idempotency key. Store it with the payslip before you send the request.

You can send the same content and reference again after a timeout, network failure, rate limit, or server error. Use exponential backoff. The API returns the existing result and does not make a second record.

Do not use the reference for different content. The API returns 409 CONFLICT and keeps the first record.

The operations report an idempotent result in different ways:

registerNonPII returns 201 for a new record. It returns 200 for an identical record that exists already.
registerNonPIIBatch returns 200 for the request. Each result has created, duplicate, or error status.
registerAndBuildBarcode does not accept a provider-generated reference. If the response is lost, encrypt the record again before you send a new request.

Reuse the original payslip data, initialisation vector (IV), and authentication tag for an idempotent retry. New encrypted content conflicts with the stored content for that reference.

Batch results

The batch response keeps the sequence of the request records. Use external_id to match each result to a record in your system.

If a record has an error, issue that payslip without a QR code. Do not delay the payslip.

Data formats

Use these references when you build an Issuer API request: