Go to home page

Patron Codes

A Patron Code is an alternative to presenting a QR code where that option isn’t available.

Patron Code Model

Attributes

  • id

    string

    The Patron Code's unique identifier.

  • barcode

    string

    ✩ Field to display in barcode format.

  • createdAt

    timestamp

    Date when the Patron Code was created.

  • assetId

    string

    Id of the related asset.

  • expiresAt

    timestamp

    Date when the Patron Code will expire.

  • appName

    string deprecated

    The app used to create the Patron Code.

  • accountId

    string

    The account id of the creator of the patron code.

  • testScenarioName

    string

    The Test Scenario Name of the Patron Code.

  • externalId

    string

    The external Id of the Patron Code.

  • metadata

    object

    Arbitrary key-value data associated with the Patron Code.

✩ Barcode is a 16 digit number. The first 6 digits are a Centrapay defined prefix, then a 9 digit code, then a luhn checksum digit.

Barcode Breakdown
9 9 9 0 0 0 1 2 3 4 5 6 7 8 9 5  ❖  complete barcode
9 9 9 0 0 0 - - - - - - - - - -  ❖  centrapay prefix
- - - - - - 1 2 3 4 5 6 7 8 9 -  ❖  code
- - - - - - - - - - - - - - - 5  ❖  luhn checksum

The Centrapay Prefix may present any of the following prefixes:

  • 121921
  • 123000
  • 282828
  • 293000
  • 321000
  • 321123
  • 636863
  • 713131
  • 765432
  • 777000
  • 839234
  • 848484
  • 888444
  • 929394
  • 987600
  • 999000

Test Scenario Name

This field is used to inject behavior into a Payment Request when the generated barcode is supplied on creation. If a Test Scenario Name is defined on a Patron Code, it is considered a test resource and can only be used with Payment Requests that will have a liveness of 'test'. The Asset Type centrapay.nzd.test is required to run test scenarios.

NameDescription
force-condition-check-photo-idThe Payment Request will have a required Merchant Condition to check photo id.

Create Patron Code

This endpoint allows you to create a Patron Code. You can find payment request information attached to a Patron Code by polling for the Payment Request using the transacting APIs.

Request
curl -X POST \
 https://service.centrapay.com/api/patron-codes \
 -H 'x-api-key: <TOKEN>'
Response
{
  "id": "V17FByEP9gm1shSG6a1Zzx",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "barcode": "9990001234567895",
  "createdAt": "2021-06-08T22:55:00.000Z",
  "expiresAt": "2021-06-08T23:00:00.000Z",
  "appName": "centrapay",
  "metadata": {}
}

Get Patron Code

This endpoint allows you to retrieve a Patron Code by id.

Request
curl -X GET \
 https://service.centrapay.com/api/patron-codes/V17FByEP9gm1shSG6a1Zzx \
 -H 'x-api-key: <TOKEN>'
Response
{
  "id": "V17FByEP9gm1shSG6a1Zzx",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "barcode": "9990001234567895",
  "createdAt": "2021-06-08T22:55:00.000Z",
  "expiresAt": "2021-06-08T23:00:00.000Z",
  "appName": "centrapay",
  "assetId": "WRhAxxWpTKb5U7pXyxQjjY",
  "metadata": {
    "deviceId": "device-001"
  }
}

Get Patron Code By Barcode

This endpoint allows you to retrieve a Patron Code by barcode.

Errors

  • CHECKSUM_FAILED

    400

    Luhn checksum digit doesn't pass.

  • PATRON_CODE_INVALID

    403

    Patron Code doesn't exist or it has expired.

Request
curl -X GET \
 https://service.centrapay.com/api/patron-codes/barcode/9990001234567895 \
 -H 'x-api-key: <TOKEN>'
Response
{
  "id": "V17FByEP9gm1shSG6a1Zzx",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "barcode": "9990001234567895",
  "createdAt": "2021-06-08T22:55:00.000Z",
  "expiresAt": "2021-06-08T23:00:00.000Z",
  "appName": "centrapay",
  "assetId": "WRhAxxWpTKb5U7pXyxQjjY",
  "metadata": {
    "deviceId": "device-001"
  }
}

Get Patron Code By Namespace and External Id

This endpoint allows you to retrieve a Patron Code by namespace and external id.

Errors

  • PATRON_CODE_INVALID

    403

    Patron Code doesn't exist or it has expired.

Request
curl -X GET \
 https://service.centrapay.com/api/patron-codes/namespace-test/external-id/3e9003bbff48d \
 -H 'x-api-key: <TOKEN>'
Response
{
  "id": "V17FByEP9gm1shSG6a1Zzx",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "barcode": "9990001234567895",
  "createdAt": "2021-06-08T22:55:00.000Z",
  "expiresAt": "2021-06-08T23:00:00.000Z",
  "externalId": "3e9003bbff48d",
  "appName": "centrapay",
  "assetId": "WRhAxxWpTKb5U7pXyxQjjY",
  "metadata": {
    "deviceId": "device-001"
  }
}

Set Patron Code Metadata

This endpoint allows you to set metadata on a Patron Code. Metadata is merged with any existing keys — only the keys provided in the request are affected. To remove a key, set its value to an empty string.

Attributes

  • metadata

    object required

    A map of key-value pairs to attach to the Patron Code. Keys must be alphanumeric with underscores or dashes (max 64 characters). Values must be strings (max 256 characters). Maximum of 10 keys.

Errors

  • PATRON_CODE_INVALID

    403

    Patron Code doesn't exist or it has expired.

Request
curl -X POST \
 https://service.centrapay.com/api/patron-codes/%7BpatronCodeId%7D/metadata \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "metadata": {
  "deviceId": "device-001"
 }
}
'
Response
{
  "patronCodeId": "V17FByEP9gm1shSG6a1Zzx",
  "createdAt": "2021-06-08T22:55:00.000Z",
  "createdBy": "crn:WRhAxxWpTKb5U7pXyxQjjY:api-key:MyApiKey",
  "metadata": {
    "deviceId": "device-001"
  }
}