Read and verify a payslip

Read the payload from the payslip QR code or its PDF metadata. Send it to the Verifier API. The API returns the registered payslip data and the employee details. For the HTTP contract, refer to the Verifier API reference.

Environments

Environment	URL for	URL
Production	API	`https://verify.verifiabl.io`
Production	Token	`https://auth.verifiabl.io/oauth/token`
Sandbox	API	`https://verify.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.

1. Authenticate

The Verifier 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://verify.verifiabl.io"
}

Send the access token with each request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Use the token again until it is near expiry. If the API returns 401, get a new token. Then send the request again one time.

2. Read the payload

Read the PDF metadata first. The property verifiabl:payload in the namespace https://verifiabl.io/ns/ contains the pipe-delimited payload. If the PDF does not have this property, decode the QR code. The QR code contains a scan URL. A copy made with print to PDF, or a photograph of the payslip, does not keep the metadata.

3. Send the payload

Send the text without changes to POST /v1/verifications/payload. Send the request body as JSON. The response body is JSON. If you send a scan URL, keep all of the text after the # character.

4. Read the response

The API returns the payslip data and the employee details in the response schema that you agreed with Verifiabl during onboarding.

The status code and code give the result for the payslip:

Status	`code`	Result
`200`		The payslip is verified. The response contains the registered payslip data and the employee details.
`400`	`DECRYPTION_FAILED`	The payload cannot be authenticated. The payslip is not verified.
`404`	`VERIFIABL_REFERENCE_NOT_FOUND`	Verifiabl has no record of this payslip.
`422`	`KEY_VERSION_UNAVAILABLE`	Verifiabl cannot decrypt this record now. Tell Verifiabl the `verifiabl_reference`.

Errors and retries

Use code to identify an error. Do not compare the error or detail text. This text can change.

After a timeout, a rate limit or a server error, send the same payload again. Use exponential backoff. The same payload gives the same verification result.

For status codes, response fields and a cURL example, refer to Verify a payslip barcode payload.

Security

Send payloads over HTTPS. For how Verifiabl stores and protects data, refer to Architecture and data handling.