Register a payslip and build its barcode badge

POST

/v1/registerAndBuildBarcode

const url = 'https://register.verifiabl.io/v1/registerAndBuildBarcode';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"schema":"au.payslip.v1","issued_at":"2026-04-04T00:00:00.000Z","payslip_non_pii":{"period_start":"2026-03-21","period_end":"2026-04-03","payment_date":"2026-04-04","currency":"AUD","pay_frequency":"fortnightly","gross_cents":360000,"taxable_gross_cents":340000,"paygw_cents":75200,"net_cents":268250,"ytd_gross_cents":4320000,"ytd_paygw_cents":902400,"earnings":[{"type":"ordinary","units":76,"rate_cents":4000,"amount_cents":304000},{"type":"overtime","units":4,"rate_cents":6000,"amount_cents":24000},{"type":"allowance","allowance_type":"tools","amount_cents":4000},{"type":"paid_leave","leave_type":"other_paid_leave","amount_cents":28000}],"salary_sacrifice":[{"type":"super","amount_cents":20000}],"deductions":[{"type":"other_post_tax","amount_cents":4550}],"superannuation":[{"contribution_type":"superannuation_guarantee","amount_cents":39840,"usi":"STA0100AU"},{"contribution_type":"salary_sacrifice","amount_cents":20000,"usi":"STA0100AU"}],"reimbursements_cents":8000},"encryption_metadata":{"iv":"ICEiIyQlJicoKSor","tag":"eHl6e3x9fn-AgYKDhIWGhw"},"encrypted_pii":"Q2lwaGVydGV4dA"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://register.verifiabl.io/v1/registerAndBuildBarcode \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "schema": "au.payslip.v1", "issued_at": "2026-04-04T00:00:00.000Z", "payslip_non_pii": { "period_start": "2026-03-21", "period_end": "2026-04-03", "payment_date": "2026-04-04", "currency": "AUD", "pay_frequency": "fortnightly", "gross_cents": 360000, "taxable_gross_cents": 340000, "paygw_cents": 75200, "net_cents": 268250, "ytd_gross_cents": 4320000, "ytd_paygw_cents": 902400, "earnings": [ { "type": "ordinary", "units": 76, "rate_cents": 4000, "amount_cents": 304000 }, { "type": "overtime", "units": 4, "rate_cents": 6000, "amount_cents": 24000 }, { "type": "allowance", "allowance_type": "tools", "amount_cents": 4000 }, { "type": "paid_leave", "leave_type": "other_paid_leave", "amount_cents": 28000 } ], "salary_sacrifice": [ { "type": "super", "amount_cents": 20000 } ], "deductions": [ { "type": "other_post_tax", "amount_cents": 4550 } ], "superannuation": [ { "contribution_type": "superannuation_guarantee", "amount_cents": 39840, "usi": "STA0100AU" }, { "contribution_type": "salary_sacrifice", "amount_cents": 20000, "usi": "STA0100AU" } ], "reimbursements_cents": 8000 }, "encryption_metadata": { "iv": "ICEiIyQlJicoKSor", "tag": "eHl6e3x9fn-AgYKDhIWGhw" }, "encrypted_pii": "Q2lwaGVydGV4dA" }'

Registers the non-PII record and returns a PNG barcode badge containing the transient ciphertext. The ciphertext and its derivatives are not persisted.

Authorizations

bearerAuth

Request Body^required

The encryption values in these structural examples are non-submittable placeholders. For each payslip, perform one AES-256-GCM encryption with a fresh, unpredictable 96-bit IV from a cryptographically secure random number generator, then use that operation’s IV and authentication tag together with its ciphertext. Never copy, mix, or reuse the example encryption values.

application/json

One of:

AU payslip v1

object

schema

required

string

Allowed values: au.payslip.v1

payslip_non_pii

required

object

period_start

required

string format: date

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$/

period_end

required

string format: date

payment_date

required

string format: date

currency

required

string

Allowed values: AUD NZD USD GBP EUR CAD SGD HKD CHF ZAR

gross_cents

required

integer

>= -9007199254740991 <= 9007199254740991

paygw_cents

required

integer

>= -9007199254740991 <= 9007199254740991

net_cents

required

integer

>= -9007199254740991 <= 9007199254740991

ytd_gross_cents

required

integer

>= -9007199254740991 <= 9007199254740991

ytd_paygw_cents

required

integer

>= -9007199254740991 <= 9007199254740991

pay_frequency

string

Allowed values: weekly fortnightly monthly quarterly

employment_basis

string

Allowed values: full_time part_time casual labour_hire voluntary_agreement death_beneficiary non_employee

engagement_type

string

Allowed values: permanent fixed_term

hourly

object

ordinary_rate_cents

required

integer

>= -9007199254740991 <= 9007199254740991

hours

required

number

amount_cents

required

integer

>= -9007199254740991 <= 9007199254740991

annual_rate_cents

integer

>= -9007199254740991 <= 9007199254740991

taxable_gross_cents

integer

>= -9007199254740991 <= 9007199254740991

stsl_withholding_cents

integer

>= -9007199254740991 <= 9007199254740991

earnings

Array

One of:

Paid leave

object

type

required

string

Allowed values: paid_leave

leave_type

required

string

Allowed values: cash_out_in_service unused_on_termination paid_parental workers_compensation ancillary_defence other_paid_leave

amount_cents

required

integer

>= -9007199254740991 <= 9007199254740991

units

number

rate_cents

integer

>= -9007199254740991 <= 9007199254740991

salary_sacrifice

Array<object>

object

type

required

string

Allowed values: super other

amount_cents

required

integer

>= -9007199254740991 <= 9007199254740991

deductions

Array<object>

object

type

required

string

Allowed values: union_professional_fees workplace_giving child_support_deduction child_support_garnishee other_post_tax

amount_cents

required

integer

>= -9007199254740991 <= 9007199254740991

superannuation

Array<object>

object

contribution_type

required

string

Allowed values: superannuation_guarantee resc salary_sacrifice

amount_cents

required

integer

>= -9007199254740991 <= 9007199254740991

usi

string

/^(\d{14}|[A-Z]{3}\d{4}[A-Z]{2})$/

fund_abn

string

/^\d{11}$/

reimbursements_cents

integer

>= -9007199254740991 <= 9007199254740991

ytd

object

taxable_cents

integer

>= -9007199254740991 <= 9007199254740991

super_cents

integer

>= -9007199254740991 <= 9007199254740991

non_taxable_cents

integer

>= -9007199254740991 <= 9007199254740991

post_tax_deductions_cents

integer

>= -9007199254740991 <= 9007199254740991

reimbursements_cents

integer

>= -9007199254740991 <= 9007199254740991

issued_at

required

string format: date-time

encryption_metadata

required

object

required

string

>= 16 characters <= 16 characters /^[A-Za-z0-9_-]+$/

tag

required

string

>= 22 characters <= 22 characters /^[A-Za-z0-9_-]+$/

key_version

string

/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.[1-9][0-9]{0,5}$/

encrypted_pii

required

string

>= 1 characters <= 2886 characters /^[A-Za-z0-9_-]+$/

Examples

Australian payslip (replace all encryption outputs)

{
  "schema": "au.payslip.v1",
  "issued_at": "2026-04-04T00:00:00.000Z",
  "payslip_non_pii": {
    "period_start": "2026-03-21",
    "period_end": "2026-04-03",
    "payment_date": "2026-04-04",
    "currency": "AUD",
    "pay_frequency": "fortnightly",
    "gross_cents": 360000,
    "taxable_gross_cents": 340000,
    "paygw_cents": 75200,
    "net_cents": 268250,
    "ytd_gross_cents": 4320000,
    "ytd_paygw_cents": 902400,
    "earnings": [
      {
        "type": "ordinary",
        "units": 76,
        "rate_cents": 4000,
        "amount_cents": 304000
      },
      {
        "type": "overtime",
        "units": 4,
        "rate_cents": 6000,
        "amount_cents": 24000
      },
      {
        "type": "allowance",
        "allowance_type": "tools",
        "amount_cents": 4000
      },
      {
        "type": "paid_leave",
        "leave_type": "other_paid_leave",
        "amount_cents": 28000
      }
    ],
    "salary_sacrifice": [
      {
        "type": "super",
        "amount_cents": 20000
      }
    ],
    "deductions": [
      {
        "type": "other_post_tax",
        "amount_cents": 4550
      }
    ],
    "superannuation": [
      {
        "contribution_type": "superannuation_guarantee",
        "amount_cents": 39840,
        "usi": "STA0100AU"
      },
      {
        "contribution_type": "salary_sacrifice",
        "amount_cents": 20000,
        "usi": "STA0100AU"
      }
    ],
    "reimbursements_cents": 8000
  },
  "encryption_metadata": {
    "iv": "ICEiIyQlJicoKSor",
    "tag": "eHl6e3x9fn-AgYKDhIWGhw"
  },
  "encrypted_pii": "Q2lwaGVydGV4dA"
}

New Zealand payslip (replace all encryption outputs)

{
  "schema": "nz.payslip.v1",
  "issued_at": "2026-04-22T00:00:00.000Z",
  "payslip_non_pii": {
    "period_start": "2026-04-06",
    "period_end": "2026-04-19",
    "payment_date": "2026-04-22",
    "currency": "NZD",
    "pay_cycle": "fortnightly",
    "tax_code": "M SL",
    "employment_type": "permanent",
    "hours_paid": 80,
    "gross_cents": 300000,
    "paye_cents": 66000,
    "net_cents": 213500,
    "ytd_gross_cents": 300000,
    "ytd_paye_cents": 66000,
    "earnings": [
      {
        "type": "ordinary",
        "units": 76,
        "rate_cents": 3750,
        "amount_cents": 285000
      },
      {
        "type": "overtime",
        "units": 4,
        "rate_cents": 3750,
        "amount_cents": 15000
      }
    ],
    "student_loan_cents": 10000,
    "kiwisaver": {
      "employee_deduction_cents": 10500,
      "employee_rate_basis_points": 350,
      "employer_contribution_cents": 10500,
      "esct_cents": 1837
    },
    "leave_balances": {
      "annual": {
        "value": 4,
        "unit": "weeks"
      },
      "sick": {
        "value": 10,
        "unit": "days"
      }
    }
  },
  "encryption_metadata": {
    "iv": "MDEyMzQ1Njc4OTo7",
    "tag": "jI2Oj5CRkpOUlZaXmJmamw"
  },
  "encrypted_pii": "Q2lwaGVydGV4dA"
}

Responses

201

The record and barcode were created.

application/json

object

verifiabl_reference

required

string

>= 22 characters <= 22 characters /^[A-Za-z0-9_-]+$/

barcode

required

object

format

required

string

Allowed values: png

data

required

string

Examples

Success

Generated barcode response (PNG data abbreviated)

{
  "verifiabl_reference": "n5waC35dPCoRtMXW5_gJqw",
  "barcode": {
    "format": "png",
    "data": "<base64-encoded 720px PNG barcode badge>"
  }
}

400

The request failed strict validation.

application/json

object

error

required

string

code

required

string

Allowed values: VALIDATION_FAILED

reason

string

detail

string

field_errors

Array<object>

object

path

required

string

message

required

string

Examples

Validation Failed

The request failed strict validation.

{
  "error": "Validation failed",
  "code": "VALIDATION_FAILED",
  "field_errors": [
    {
      "path": "payslip_non_pii.net_cents",
      "message": "Invalid input: expected int, received number"
    },
    {
      "path": "encryption_metadata.iv",
      "message": "IV must be exactly 16 base64url characters (96 bits)"
    }
  ]
}

401

The bearer token is missing or invalid.

application/json

object

error

required

string

code

required

string

Allowed values: UNAUTHORIZED

reason

string

detail

string

field_errors

Array<object>

object

path

required

string

message

required

string

Examples

Unauthorized

The bearer token is missing or invalid.

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

403

The authenticated principal cannot use this operation.

application/json

object

error

required

string

code

required

string

Allowed values: FORBIDDEN

reason

string

detail

string

field_errors

Array<object>

object

path

required

string

message

required

string

Examples

Forbidden

The authenticated principal cannot use this operation.

{
  "error": "Forbidden",
  "code": "FORBIDDEN"
}

409

The IV has already been used by this issuer.

application/json

object

error

required

string

code

required

string

Allowed values: IV_REUSED

reason

string

detail

string

field_errors

Array<object>

object

path

required

string

message

required

string

Examples

IV Reused

The IV has already been used by this issuer.

{
  "error": "Conflict",
  "code": "IV_REUSED",
  "detail": "encryption_metadata.iv has already been used by this issuer; re-encrypt the record with a fresh iv"
}

413

The JSON request body exceeds the route limit.

application/json

object

error

required

string

code

required

string

Allowed values: PAYLOAD_TOO_LARGE

reason

string

detail

string

field_errors

Array<object>

object

path

required

string

message

required

string

Examples

Payload Too Large

The JSON request body exceeds the route limit.

{
  "error": "Request body too large",
  "code": "PAYLOAD_TOO_LARGE"
}

415

The request Content-Type is not supported.

application/json

object

error

required

string

code

required

string

Allowed values: UNSUPPORTED_MEDIA_TYPE

reason

string

detail

string

field_errors

Array<object>

object

path

required

string

message

required

string

Examples

Unsupported Media Type

The request Content-Type is not supported.

{
  "error": "Unsupported media type",
  "code": "UNSUPPORTED_MEDIA_TYPE"
}

429

The request exceeded an IP or client rate limit.

application/json

object

error

required

string

code

required

string

Allowed values: RATE_LIMITED

reason

string

detail

string

field_errors

Array<object>

object

path

required

string

message

required

string

Examples

Rate Limited

The request exceeded an IP or client rate limit.

{
  "error": "Too many requests",
  "code": "RATE_LIMITED",
  "detail": "Retry after the rate limit resets."
}

Headers

Retry-After

required

integer

<= 9007199254740991

Seconds to wait before retrying.

Example

500

An unexpected internal error occurred.

application/json

object

error

required

string

code

required

string

Allowed values: INTERNAL_ERROR

reason

string

detail

string

field_errors

Array<object>

object

path

required

string

message

required

string

Examples

Internal Error

An unexpected internal error occurred.

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

503

A required service dependency or configuration is unavailable.

application/json

object

error

required

string

code

required

string

Allowed values: SERVICE_UNAVAILABLE

reason

string

detail

string

field_errors

Array<object>

object

path

required

string

message

required

string

Examples

Service Unavailable

A required service dependency or configuration is unavailable.

{
  "error": "Service temporarily unavailable",
  "code": "SERVICE_UNAVAILABLE",
  "detail": "Please retry with exponential backoff."
}

Headers

Retry-After

required

integer

<= 9007199254740991

Seconds to wait before retrying.

Register a payslip and build its barcode badge

Authorizations

Request Bodyrequired

Examples

Responses

201

Examples

400

Examples

401

Examples

403

Examples

409

Examples

413

Examples

415

Examples

429

Examples

Headers

Example

500

Examples

503

Examples

Headers

Example

Request Body^required