Tokens

Tokens are Assets which can only be spent in full.

Every Token is associated with a Collection, which defines the branding and general rules for the Tokens, such as active duration.

A Redemption Condition is created for each Merchant that accepts Tokens from a Collection, and contains additional conditions specific to that Merchant, such as redeemable product identifiers.

Token Collection Model

Attributes

name
string
The display name of the Collection.
accountId
string
The Account that will own the Collection.
tokenExpiresAfter
object
The active duration of all Tokens created from this Collection. See Token Expires After Model.
tokenExpiresAt
timestamp
A date that all tokens will expire on if they haven’t expired earlier.
type
stringrequired
The type of value gained by redeeming Tokens. Valid values are product and discount.
maxValue
monetary
The maximum agreed value that any merchants will be settled for a Token redemption. Required for Collections of type discount, where it defines the value that each Token will discount from a payment.
id
string
The unique identifier of the Token Collection.
test
boolean
true if the Token Collection is for testing purposes only.
status
string
The status of the Token Collection. Valid values: active.
createdAt
timestamp
Timestamp at which the Token Collection was created.
createdBy
crn
The identity that created the Token Collection.
mediaUploadId
string
The id of the Media Upload image of the Collection.
externalId
string
An identifier to associate the Collection with an external campaign or event.
img
string
The img URL of the Collection.
issuer
string
The name of the Business linked to the Account.

Token Expires After Model

Attributes

period
stringrequired
Supported values are hour, day, week, month and year.
duration
stringrequired
Number of period until token expiration.
ceil
string
Interval to round token expiry up to. Supported values are hour, day, week, month and year.

Redemption Condition Model experimental

Attributes

merchantId
string
The identifier of the Merchant that is accepting the collection.
allowedProducts
object
List of Allowed Products. Required for collections of type product.
id
string
The unique identifier of the Redemption Condition.
collectionId
string
The Token Collection that will govern the branding and redemption rules for the Token.
createdAt
timestamp
Timestamp at which the Redemption Condition was created.
createdBy
crn
The identity that created the activity.

Allowed Products Model experimental

Attributes

sku
string
The SKU of the product that is to be accepted.
name
string
Display name of the product.
maxValue
monetary
The maximum value that the product can be redeemed for.

Token Model experimental

Attributes

collectionId
string
The Token Collection that will govern the branding and redemption rules for the token.
idempotencyKey
string
Client-supplied identifier that prevents double creation.
externalId
string
The asset identifier from the issuing system.
accountId
string
The Account to create the token for. Defaults to the Account on the Token Collection.

Create Token Collection experimental

This endpoint allows you to create a Token Collection.

Attributes

name
stringrequired
The display name of the Collection.
accountId
stringrequired
The Account that will own the Collection.
tokenExpiresAfter
object
The active duration of all Tokens created from this Collection. See Token Expires After Model.
tokenExpiresAt
timestamp
A date that all tokens will expire on if they haven’t expired earlier.
type
stringrequired
The type of value gained by redeeming Tokens. Valid values are product and discount.
maxValue
monetary
The maximum agreed value that any merchants will be settled for a Token redemption. Required for Collections of type discount, where it defines the value that each Token will discount from a payment.
mediaUploadId
string
The id of the Media Upload image of the Collection.
externalId
string
An identifier to associate the Collection with an external campaign or event.

Errors

EXTERNAL_ID_ALREADY_USED
403
A collection has already been created for this account with the given externalId.

curl -X POST https://service.centrapay.com/api/collections \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "name": "Bread",
  "accountId": "T3y6hogYA4d612BExypWYH",
  "tokenExpiresAfter": {
    "period": "month",
    "duration": "1"
  },
  "maxValue": {
    "currency": "NZD",
    "amount": "400"
  },
  "type": "product",
  "mediaUploadId": "12345",
  "externalId": "ABC"
}'

{
  "id": "c_Xv990BzkgfoDS7bBls50pd",
  "name": "Bread",
  "accountId": "T3y6hogYA4d612BExypWYH",
  "tokenExpiresAfter": {
    "period": "month",
    "duration": "1"
  },
  "maxValue": {
    "currency": "NZD",
    "amount": "400"
  },
  "test": true,
  "type": "product",
  "status": "active",
  "createdBy": "crn::user:b657195e-dc2f-11ea-8566-e7710d592c99",
  "createdAt": "2021-05-12T04:30:11.001Z",
  "mediaUploadId": "12345",
  "img": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743",
  "issuer": "Centrapay",
  "externalId": "ABC"
}

List Token Collections experimental

Returns a paginated list of Token Collections for an Account.

Attributes

pageKey
string
Used to retrieve the next page of items.

curl -X GET 'https://service.centrapay.com/api/accounts/T3y6hogYA4d612BExypWYH/collections?pageKey=Collection%232G5bXm4dnuDHnnKY8WeCPm%7C%23Collection%7C8vq4kn03o0g1grrihk7ooloizpqt2y' \
-H 'x-api-key: <TOKEN>'

{
  "nextPageKey": "Collection#E9eXsErwA444qFDoZt5iLA|#Collection",
  "items": [
    {
      "id": "c_Xv990BzkgfoDS7bBls50pd",
      "name": "Bread",
      "accountId": "T3y6hogYA4d612BExypWYH",
      "tokenExpiresAfter": {
        "period": "month",
        "duration": "1"
      },
      "maxValue": {
        "currency": "NZD",
        "amount": "400"
      },
      "test": true,
      "type": "product",
      "status": "active",
      "createdBy": "crn::user:b657195e-dc2f-11ea-8566-e7710d592c99",
      "createdAt": "2021-05-12T04:30:11.001Z",
      "mediaUploadId": "12345",
      "img": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743",
      "issuer": "Centrapay"
    }
  ]
}

Create Redemption Condition experimental

This endpoint allows you to create a Redemption Condition. Redemption conditions are only created for Token Collections of type product.

Attributes

merchantId
stringrequired
The identifier of the Merchant that is accepting the collection.
allowedProducts
objectrequired
List of Allowed Products.

Errors

INVALID_AMOUNT
403
One or more of the maxValue amount in the products has exceeded the maxValue amount defined on the collection.
REDEMPTION_CONDITION_ALREADY_EXISTS
403
A redemption condition for the collection and the merchant has already been created.
COLLECTION_INVALID_TYPE
403
Redemption conditions can only be created for collections of type product.

curl -X POST https://service.centrapay.com/api/collections/c_NFhUgPQEYbk2EbTXAYArTX/redemption-conditions \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "merchantId": "36EALpZ89XpShxM2Ee9sXT",
  "allowedProducts": [
    {
      "sku": "100001",
      "name": "White Bread",
      "maxValue": {
        "currency": "NZD",
        "amount": "400"
      }
    },
    {
      "sku": "100002",
      "name": "Sourdough Bread",
      "maxValue": {
        "currency": "NZD",
        "amount": "800"
      }
    }
  ]
}'

{
  "id": "1234",
  "merchantId": "36EALpZ89XpShxM2Ee9sXT",
  "collectionId": "c_NFhUgPQEYbk2EbTXAYArTX",
  "allowedProducts": [
    {
      "sku": "100001",
      "name": "White Bread",
      "maxValue": {
        "currency": "NZD",
        "amount": "400"
      }
    },
    {
      "sku": "100002",
      "name": "Sourdough Bread",
      "maxValue": {
        "currency": "NZD",
        "amount": "800"
      }
    }
  ],
  "createdAt": "2022-05-12T04:30:11.001Z",
  "createdBy": "crn::user:b657195e-dc2f-11ea-8566-e7710d592c99"
}

Set Allowed Products for Redemption Condition experimental

This endpoint allows you to set Allowed Products for a Redemption Condition.

Attributes

allowedProducts
objectrequired
List of Allowed Products. Required for collections of type product.

Errors

INVALID_AMOUNT
403
One or more of the maxValue amount in the products has exceeded the maxValue amount defined on the collection.

curl -X POST https://service.centrapay.com/api/collections/c_NFhUgPQEYbk2EbTXAYArTX/redemption-conditions/DKTs3U38hdhfEqwF1JKoT2/set-allowed-products \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "allowedProducts": [
    {
      "sku": "100001",
      "name": "White Bread",
      "maxValue": {
        "currency": "NZD",
        "amount": "400"
      }
    },
    {
      "sku": "100002",
      "name": "Sourdough Bread",
      "maxValue": {
        "currency": "NZD",
        "amount": "800"
      }
    }
  ]
}'

{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "merchantId": "36EALpZ89XpShxM2Ee9sXT",
  "collectionId": "c_NFhUgPQEYbk2EbTXAYArTX",
  "allowedProducts": [
    {
      "sku": "100001",
      "name": "White Bread",
      "maxValue": {
        "currency": "NZD",
        "amount": "400"
      }
    },
    {
      "sku": "100002",
      "name": "Sourdough Bread",
      "maxValue": {
        "currency": "NZD",
        "amount": "800"
      }
    }
  ],
  "createdAt": "2022-05-12T04:30:11.001Z",
  "createdBy": "crn::user:b657195e-dc2f-11ea-8566-e7710d592c99",
  "updatedAt": "2022-11-12T04:30:11.001Z",
  "updatedBy": "crn::user:b657195e-dc2f-11ea-8566-e7710g542c49"
}

Create Token experimental

This endpoint allows you to create a Token.

Attributes

collectionId
stringrequired
The Token Collection that will govern the branding and redemption rules for the token. Currently only Collections of type product are supported.
idempotencyKey
stringrequired
Client-supplied identifier that prevents double creation.
externalId
string
The asset identifier from the issuing system.
accountId
string
The Account to create the token for. Defaults to the Account on the Token Collection.

Errors

TOKEN_ALREADY_CREATED
403
Token with supplied parameters already exists.
LIVENESS_MISMATCH
403
The account is test and the collection's liveness is main or vice versa.

curl -X POST https://service.centrapay.com/api/tokens \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "collectionId": "c_Jaim1Cu1Q55uooxSens6yk",
  "idempotencyKey": "payment-de32dd90-b46c-11ea-93c3-83a333b86e7b",
  "externalId": "23403283262"
}'

{
  "id": "pe32dd90-b46c-11ea-92828sa",
  "accountId": "WRhAxxWpTKb5U7pXyxQjjP",
  "category": "token",
  "collectionId": "c_Jaim1Cu1Q55uooxSens6yk",
  "status": "active",
  "createdAt": "2021-01-17T18:00:23.000Z",
  "activeFrom": "2021-01-17T18:00:23.000Z",
  "expiresAt": "2022-01-18T18:00:23.000Z",
  "liveness": "test",
  "createdBy": "crn:1234abc:api-key:MyAssetIssuerKey",
  "description": "My Cafe Token",
  "issuerImg": "https://static.centrapay.com/assets/brands/centraperk/logo.png",
  "img": "https://static.centrapay.com/assets/brands/centraperk/cafe-token.png",
  "issuer": "Centraperk Cafe",
  "issuerWebsite": "www.centraperk-cafe.com",
  "type": "centrapay.token.test",
  "externalId": "23403283262"
}

Token Collection Model

Attributes

name

accountId

tokenExpiresAfter

tokenExpiresAt

type

maxValue

id

test

status

createdAt

createdBy

mediaUploadId

externalId

img

issuer

Token Expires After Model

Attributes

period

duration

ceil

Redemption Condition Model experimental

Attributes

merchantId

allowedProducts

id

collectionId

createdAt

createdBy

Allowed Products Model experimental

Attributes

sku

name

maxValue

Token Model experimental

Attributes

collectionId

idempotencyKey

externalId

accountId

Create Token Collection experimental

Attributes

name

accountId

tokenExpiresAfter

tokenExpiresAt

type

maxValue

mediaUploadId

externalId

Errors

EXTERNAL_ID_ALREADY_USED

List Token Collections experimental

Attributes

pageKey

Create Redemption Condition experimental

Attributes

merchantId

allowedProducts

Errors

INVALID_AMOUNT

REDEMPTION_CONDITION_ALREADY_EXISTS

COLLECTION_INVALID_TYPE

Set Allowed Products for Redemption Condition experimental

Attributes

allowedProducts

Errors

INVALID_AMOUNT

Create Token experimental

Attributes

collectionId

idempotencyKey

externalId

accountId

Errors

TOKEN_ALREADY_CREATED

LIVENESS_MISMATCH