Use the Issuer API

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

Environments

Environment	URL for	URL
Production	API	`https://register.verifiabl.io`
Production	Token	`https://auth.verifiabl.io/oauth/token`
Sandbox	API	`https://register.sandbox.verifiabl.io`
Sandbox	Token	`https://auth.sandbox.verifiabl.io/oauth/token`

When you get a token, set audience to the API URL for the environment. Use sandbox credentials in sandbox. The examples on this page use production.

Send each request body as JSON. Each response body is JSON.

Authentication

The Issuer API uses OAuth 2.0 client credentials. Use the client ID and client secret from your onboarding to get an 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"
}

Send the returned access token with each request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Cache the token until its expiry is near. After a 401 response, request a new token. Then send the request one more time.

Select an operation

Use the operation that matches how you issue payslips:

Use registerNonPII to register one record. Then make the QR code.
Use registerNonPIIBatch to register up to 1,000 records for a pay run.
Use registerAndBuildBarcode if you cannot make the QR code. The response contains a PNG of the QR code.

The issuing guides show the complete workflow. For Australian and New Zealand v2 payslips, use the SDK helper for the payslip’s country. The helper validates the non-PII data and encrypts the PII. For advanced integrations, use the low-level APIs.

For au.payslip.v2 and nz.payslip.v2, send only the documented non-PII fields of the Australian or the New Zealand payslip schema. The Issuer API validates each request. Keep identifying details in the encrypted PII profile, not in the non-PII fields.

Handle errors

Each operation page lists its status codes and error responses. Use code in conditional statements. Do not compare error or detail.

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

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

Rate limits

The limit is 6,000 requests a minute for each organisation and each IP address. A registerNonPIIBatch request counts as one request. Use it for pay runs.

If you send more, the API returns 429 until the minute ends. Wait 60 seconds or more. Then send the same content and reference again. Check for the status 429, not the error code.

Idempotency and retries

For registerNonPII and registerNonPIIBatch, make a verifiabl_reference for each payslip in your system. Make it from 16 random bytes, encoded as 22 base64url characters. For the rules, refer to Generating your own Verifiabl references. The reference is the idempotency key. Save it with the payslip before you send the request.

You can send the same content and reference again after a timeout, network failure, or server error. Use exponential backoff. After a rate limit, refer to Rate limits. 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 reference from your system. If the response is lost, encrypt the record again before you send a new request.

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

The SDKs retry temporary failures. For the retry rules and the timeout for a pay run, refer to Retries and timeouts.

Batch results

The batch results are in the same order as the request records. To identify a record in the results, send external_id.

For a pay run of more than 1,000 records, send the batches one at a time. If the API is busy, it returns 503 with a Retry-After header.

Test your payslips

In sandbox, you can verify the payslips that your organisation registered. Refer to Test your payslips in sandbox.

Data formats

Use these references when you build an Issuer API request: