Go to home page
Docs

Guides

Creating Digital Tokens

Digital tokens are assets that can be exchanged for specific products or deals. Think a “Free coffee” coupon or a “50% off” voucher. Unlike assets such as gift cards or currency, tokens can only be spent in their entirety, all at once.

Token Collection

A collection is a grouping of tokens that share the same attributes and redemption conditions, e.g.

  • Name
  • Icon
  • Expiry period
  • Maximum redemption value

Redemption Conditions

A redemption condition allows a Merchant  API  to accept tokens from a token collection. It contains redemption details specific to that merchant, e.g. redeemable product SKUs.

Implementation

Loading Diagram...

  1. Create Collection

    You can create Collections by calling our Create Token Collection  API  endpoint. You will need the account identifier of the owning account for the accountId field. The maxValue field is optional, and defines the upper limit on any settlement amount for a redeemed token.

    Request
    POST/api/collections
    curl -X POST https://service.centrapay.com/api/collections \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bread",
    "accountId": "T3y6hogYA4d612BExypWYH",
    "tokenExpiresAfter": {
      "period": "month",
      "duration": "1"
    },
    "maxValue": {
      "currency": "NZD",
      "amount": "400"
    },
    "type": "product"
  }'

  2. Create Redemption Condition for each merchant, using the collection Id from step 1

    Redemption Conditions are created by calling the Create Redemption Condition  API  endpoint. You will need the merchant identifier for the merchantId field. The list of allowedProducts defines those products sold by the merchant that are eligible for redemption. The sku for the product will need to match the sku that is passed in with the line item when the merchant creates the payment during redemption: Create Payment Request  API .

    Request
    POST/api/collections/{collectionId}/redemption-conditions
    curl -X POST https://service.centrapay.com/api/collections/NFhUgPQEYbk2EbTXAYArTX/redemption-conditions \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "36EALpZ89XpShxM2Ee9sXT",
    "allowedProducts": [
      {
        "sku": "100001",
        "name": "White Bread",
        "maxValue": {
          "currency": "NZD",
          "amount": "400"
        }
      },
      {
        "sku": "100002",
        "name": "Sourdough Bread",
        "maxValue": {
          "currency": "NZD",
          "amount": "800"
        }
      }
    ]
  }'

  3. Create Token

    Tokens can be created for the collection by calling the Create Token  API  endpoint.

    Request
    POST/api/tokens
    curl -X POST https://service.centrapay.com/api/tokens \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "NFhUgPQEYbk2EbTXAYArTX",
    "idempotencyKey": "token-de32dd90-b46c-11ea-93c3-83a333b86e7b"
  }'

    To create tokens directly into a user account, call our Create Token  API  endpoint and include the user’s accountId in your request.

    Request
    POST/api/tokens
    curl -X POST https://service.centrapay.com/api/tokens \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "NFhUgPQEYbk2EbTXAYArTX",
    "idempotencyKey": "token-de32dd90-b46c-11ea-93c3-83a333b86e7b",
    "accountId": "WRhAxxWpTKb5U7pXyxQjjP"
  }'

  4. Transfer Token

    For sending tokens to users, see Sending Assets