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 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 to accept tokens from a token collection. It contains redemption details specific to that merchant, e.g. redeemable product SKUs.

Implementation

    sequenceDiagram
  autonumber
  Token Issuer ->> Centrapay: Create Collection
  Note left of Token Issuer: Confirm redeemable product<br/>IDs with merchant
  Token Issuer ->> Centrapay: Create Redemption Condition
  Token Issuer ->> Centrapay: Create Token
  opt
    Token Issuer ->> Centrapay: Transfer Token
  end
  

1. Create Collection

   You can create Collections by calling our Create Token Collection 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.

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

   curl -X POST https://service.centrapay.com/api/collections/c_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 endpoint.

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

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

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

4. Transfer Token

   For sending tokens to users, see Sending Assets