Tokens - Centrapay Docs

Tokens are Assets API 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 API 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 API 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 API 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 API linked to the Account.

Token Expires After Model

Attributes

period
string
Supported values are hour, day, week, month and year.
duration
string
Number of period until token expiration.

Redemption Condition Model experimental

Attributes

merchantId
string
The identifier of the Merchant API 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
stringrequired
The display name of the Collection.
accountId
stringrequired
The Account API 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 API 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.

Request

POST/api/collections

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

Response

{
  "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 API list of Token Collections for an Account.

Attributes

pageKey
string
Used to retrieve the next page of items.

Request

GET/api/accounts/T3y6hogYA4d612BExypWYH/collections

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

Response

{
  "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
stringrequired
The identifier of the Merchant API that is accepting the collection.
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.
REDEMPTION_CONDITION_ALREADY_EXISTS
403
A redemption condition for the collection and the merchant has already been created.

Request

POST/api/collections/c_NFhUgPQEYbk2EbTXAYArTX/redemption-conditions

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

Response

{
  "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
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.

Request

POST/api/collections/c_NFhUgPQEYbk2EbTXAYArTX/redemption-conditions/DKTs3U38hdhfEqwF1JKoT2/set-allowed-products

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

Response

{
  "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
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.

Request

POST/api/tokens

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

Response

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

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