Test your payslips in sandbox

In sandbox, you can verify the payslips that your organisation registered. Verifiabl does not charge for these tests.

Test in the provider portal

Before you use the API, you can test a payslip by hand:

Sign in to the provider portal at https://manage.sandbox.verifiabl.io.
Open Verify a payslip.
Choose the payslip PDF or image, or paste its scan link.

The portal shows the verified payslip data. If the test fails, it shows the cause.

Test with the API

Use the API in your integration tests. This operation is not available in production.

For the HTTP contract, refer to POST /v1/issuer-test/verifications/payload.

Environment

URL for	URL
API	`https://verify.sandbox.verifiabl.io`
Token	`https://auth.sandbox.verifiabl.io/oauth/token`

1. Get a token

Use the client ID and client secret of your sandbox Issuer API client. Set audience to the sandbox Verifier API URL. Set scope to verifiabl:issuer-test.

POST https://auth.sandbox.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.sandbox.verifiabl.io",
  "scope": "verifiabl:issuer-test"
}

This token is for test requests only. To register payslips, use a token for the Issuer API.

If the token request returns an error, ask Verifiabl to enable test requests for your sandbox client.

2. Send the payload

Register a payslip in sandbox. Then read its payload from the QR code or the PDF metadata. The verifier guide shows how to read the payload.

Send the payload without changes in barcode:

POST https://verify.sandbox.verifiabl.io/v1/issuer-test/verifications/payload
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "barcode": "YOUR_PAYLOAD"
}

3. Read the response

Status	`code`	Result
`200`		The payslip is verified. The response contains the registered payslip data and the employee details.
`400`	`VALIDATION_FAILED`	The request body is not valid. `barcode` must contain 1 to 13,000 characters. Use the `path` of each item in `field_errors` to find the request field.
`400`	`DECRYPTION_FAILED`	The payload cannot be decrypted. Use `reason` to find the cause.
`401`	`UNAUTHORIZED`	The token is missing, not valid or expired. Make sure that its `audience` is the sandbox Verifier API URL. Get a new token. Then send the request again.
`403`	`FORBIDDEN`	If `reason` is `issuer_mismatch`, another organisation registered the payslip. If there is no `reason`, the token is not valid for this operation. Get a token for your sandbox Issuer API client with only the `verifiabl:issuer-test` scope.
`404`	`VERIFIABL_REFERENCE_NOT_FOUND`	Verifiabl has no record of this payslip in sandbox.
`404`	`NOT_FOUND`	This operation is not available at this URL. Send the request to the sandbox API URL.
`422`	`KEY_VERSION_UNAVAILABLE`	Verifiabl cannot decrypt this record now. Tell Verifiabl the `verifiabl_reference`.
`429`	`RATE_LIMITED`	Your organisation sent too many test requests. Wait for the number of seconds in the `Retry-After` header. Then send the request again.

Decryption reasons

A 400 DECRYPTION_FAILED response in sandbox contains reason:

`reason`	Cause
`no_key_matched`	None of your organisation’s active keys decrypts the payload. Encrypt the PII with your current sandbox key.
`invalid_utf8`	The decrypted PII is not valid UTF-8.
`profile_schema_mismatch`	The PII format does not agree with the `schema` of the registered payslip.
Other values	The decrypted PII does not follow the PII format. The value identifies the rule.

Use code and reason in conditional statements. Do not compare error or detail.