Tokens - Centrapay Docs

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
string required

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
string required

Supported values are hour, day, week, month and year.
duration
string required

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.

POST /api/collections

Create Token Collection experimental

This endpoint allows you to create a Token Collection.

Attributes

name
string required

The display name of the Collection.
accountId
string required

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
string required

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"
}

GET /api/accounts/{accountId}/collections

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"
    }
  ]
}

POST /api/collections/{collectionId}/redemption-conditions

Create Redemption Condition experimental

This endpoint allows you to create a Redemption Condition.

Attributes

merchantId
string required

The identifier of the Merchant that is accepting the collection.
allowedProducts
object required

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.
REDEMPTION_CONDITION_ALREADY_EXISTS
403

A redemption condition for the collection and the merchant has already been created.

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"
}

POST /api/collections/{collectionId}/redemption-conditions/{redemptionConditionId}/set-allowed-products

Set Allowed Products for Redemption Condition experimental

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

Attributes

allowedProducts
object required

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"
}

—

POST /api/tokens

Create Token experimental

This endpoint allows you to create a Token.

Attributes

collectionId
string required

The Token Collection that will govern the branding and redemption rules for the token. Currently only Collections of type product are supported.
idempotencyKey
string required

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

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