Tokens

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.


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.

  • type

    string

    The type of value exchanged when redeeming Tokens. Valid values: “product”.

  • maxValue

    monetary

    The maximum agreed value that any merchants will be settled for a Token redemption.

  • 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.


Attributes

  • period

    string

    Supported values are hour, day, week, month and year.

  • duration

    string

    Number of period until token expiration.


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.


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.


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

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

    objectrequired

    The active duration of all Tokens created from this Collection. See Token Expires After Model.

  • type

    stringrequired

    The type of value exchanged when redeeming Tokens. Valid values: “product”.

  • maxValue

    monetary

    The maximum agreed value that any merchants will be settled for a Token redemption.

  • 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": "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

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

This endpoint allows you to create a Redemption Condition.

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.

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/NFhUgPQEYbk2EbTXAYArTX/redemption-conditions
curl -X POST \
 https://service.centrapay.com/api/collections/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": "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/tokens

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.

  • 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": "Jaim1Cu1Q55uooxSens6yk",
 "idempotencyKey": "payment-de32dd90-b46c-11ea-93c3-83a333b86e7b",
 "externalId": "23403283262"
}
'
Response
{
  "id": "pe32dd90-b46c-11ea-92828sa",
  "accountId": "WRhAxxWpTKb5U7pXyxQjjP",
  "category": "token",
  "collectionId": "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"
}