Assets - Centrapay Docs

Centrapay digital assets are resources that represent the ability for a Centrapay account to perform transactions where value is exchanged. Assets can be spent to satisfy Payment Requests API , withdrawn to a bank account via Funds Transfers API and sent to other Centrapay users via Asset Transfers API .

Assets are categorized as either Money or Tokens. Depending on its asset category, an asset will have different attributes available and different rules governing how it can be obtained, shared or spent.

Asset Model

All assets have the following fields along with the additional fields that are specific to its category. Assets which don’t have a category are considered experimental and the model may change.

Attributes

id
string
The Asset’s unique identifier.
accountId
string
The Asset’s owning Centrapay Account id.
category
string
Asset category (“money”, “giftcard”, “token”).
type
string
Asset Type API id used by payment option asset types.
liveness
string
Either “main” (live payments allowed) or “test”.
description
string
Displayable asset description.
createdAt
timestamp
Date when the asset was created or issued.
status
string
“active” if the asset can be used for payments.
meta
objectexperimental
Additional data that may only appear in the Get Asset response.
name
stringexperimental
The name of the asset when created from an enduring payment consent API . Only valid for quartz.nzd assets.

Money Model

Money assets, being backed by real currency, are the most flexible asset types. Money is accepted for most payment requests, can be sent in arbitrary amounts and does not expire.

Money assets have the following attributes along with the base asset fields.

Attributes

currency
string
Currency code, eg “NZD”.
balance
bignumber
Current balance in the currency’s smallest denomination (ie. cents).
availableBalance
bignumber
The balance of the asset that is available for transfers or purchases.
settlement
booleanexperimental
The asset is configured for Settlements API .
period
stringexperimental
The period after which the balance will be reset. This field is only available on the quartz API asset type. Possible values are daily, weekly, fortnightly, monthly or yearly.
periodStartedAt
timestampexperimental
Datetime when the current period was started. This field is only available on the quartz API asset type.
periodEndingAt
timestampexperimental
Datetime when the current period will end. This field is only available on the quartz API asset type.

Token Model experimental

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.

Tokens have the following attributes along with the base asset fields.

Attributes

collectionId
string
The token collection API that will govern the branding and redemption rules for the token.
createdBy
crn
The identity that created the activity.
activeFrom
timestamp
The date when the asset becomes spendable.
expiresAt
timestamp
The date when the asset expires.
img
string
The img URL of the token.
issuer
string
The name of the Business API that issued the token.
issuerWebsite
string
The URL of the issuer of the token.
issuerImg
string
The img URL of the issuer that the token belongs to.
externalId
string
The asset identifier from the issuing system.

Ledger Model experimental

A ledger is a single asset that maintains a balance of multiple tokens belonging to an account. All tokens in a ledger come from a specific collection. Multiple tokens can be spent or sent at once from the ledger.

Ledgers have the following attributes along with the base asset fields.

Attributes

collectionId
string
The Token Collection API that all tokens in the ledger belong to.
collectionType
string
The type of the token collection.
tokenValue
monetary
The value of each token in the ledger. Taken from the maxValue property on the token collection.
createdBy
crn
The identity that created the ledger.
expiresAt
timestamp
The date when the ledger expires.
balanceExpiresAfter
object
The active duration of tokens that are issued to this ledger.
img
string
The img URL of the ledger.
issuerAccountId
string
The ID of the Account that issued the tokens in the ledger.
balance
bignumber
Current number of tokens in the ledger.

GET/api/assets/{assetId}

Get Asset

Request

GET/api/assets/L75M3L56N2PtBSt8g7uXLU

curl -X GET \
 https://service.centrapay.com/api/assets/L75M3L56N2PtBSt8g7uXLU \
 -H 'x-api-key: <TOKEN>'

Response

{
  "id": "L75M3L56N2PtBSt8g7uXLU",
  "accountId": "9aFdxZNbqmFhzJFqozreqesEeaoh2f",
  "category": "token",
  "type": "centrapay.token.main",
  "liveness": "main",
  "createdAt": "2024-04-23T22:11:57.158Z",
  "status": "active",
  "activeFrom": "2024-04-23T22:11:56.924Z",
  "expiresAt": "2024-05-07T22:11:56.924Z",
  "description": "Centrapay Token",
  "collectionId": "1234",
  "issuerImg": "https://static.centrapay.com/assets/brands/centraperk/logo.png",
  "img": "http://www.centrapay.com/path/to/img.png",
  "issuer": "Centraperk",
  "issuerWebsite": "www.centrapay.com",
  "mediaUploadId": "P9picAvVyA7c7d1GMytWG7"
}

GET/api/assets/{assetId}/summary

Get Asset Summary

Request

GET/api/assets/L75M3L56N2PtBSt8g7uXLU/summary

curl -X GET \
 https://service.centrapay.com/api/assets/L75M3L56N2PtBSt8g7uXLU/summary

Response

{
  "id": "L75M3L56N2PtBSt8g7uXLU",
  "issuer": "Centraperk Cafe",
  "description": "Free Coffee",
  "expiresAt": "2020-12-31T00:00:00.000Z",
  "img": "https://static.centrapay.com/assets/brands/centraperk/cafe-token.png",
  "liveness": "test"
}

GET/api/accounts/{accountId}/assets

List Assets for Account

Returns a paginated API list of Assets for an account. This will not return archived assets.

Attributes

externalId
string
The asset identifier from the issuing system.

Request

GET/api/accounts/Te2uDM7xhDLWGVJU3nzwnh/assets

curl -X GET \
 https://service.centrapay.com/api/accounts/Te2uDM7xhDLWGVJU3nzwnh/assets \
 -H 'x-api-key: <TOKEN>'

Response

{
  "items": [
    {
      "id": "WRhAxxWpTKb5U7pXyxQjjY",
      "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
      "category": "money",
      "type": "centrapay.nzd.main",
      "liveness": "main",
      "description": "NZD",
      "createdAt": "2021-01-01T00:00:00.000Z",
      "status": "active",
      "currency": "NZD",
      "balance": "2000"
    },
    {
      "id": "Aj7rtHmd7rDeWoJgw9MPHe",
      "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
      "type": "cca.coke.main",
      "description": "Coke™ Token",
      "category": "token",
      "value": [
        {
          "currency": "NZD",
          "amount": "400"
        }
      ],
      "expiresAt": "2020-12-31T00:00:00.000Z",
      "createdAt": "2020-05-01T12:30:00.000Z"
    }
  ]
}

POST/api/assets/{assetId}/archive

Archive Asset

Archive supported asset types by asset id. Currently tokens, and quartz.nzd assets may be archived.

Errors

UNSUPPORTED_ASSET_TYPE
403
Asset type can not be archived

Request

POST/api/assets/V1NXc8KJC7b8QKGws13hYR/archive

curl -X POST \
 https://service.centrapay.com/api/assets/V1NXc8KJC7b8QKGws13hYR/archive \
 -H 'x-api-key: <TOKEN>'

Response

{
  "id": "V1NXc8KJC7b8QKGws13hYR",
  "accountId": "9gXmHuaFsiG6gmh6zoUDXCsJ6rtYA8",
  "category": "token",
  "type": "centrapay.token.main",
  "liveness": "main",
  "createdAt": "2024-04-23T22:07:05.738Z",
  "status": "archived",
  "activeFrom": "2024-04-23T22:07:05.602Z",
  "expiresAt": "2024-05-07T22:07:05.602Z",
  "description": "Centrapay Token",
  "collectionId": "1234",
  "issuerImg": "https://static.centrapay.com/assets/brands/centraperk/logo.png",
  "issuer": "Centraperk",
  "issuerWebsite": "www.centrapay.com"
}

GET/api/assets/{assetType}/external-id/{externalId}

Get Asset by External Id

Request

GET/api/assets/centrapay.token.main/external-id/TiYi6haDzdkasmdfhIGz

curl -X GET \
 https://service.centrapay.com/api/assets/centrapay.token.main/external-id/TiYi6haDzdkasmdfhIGz \
 -H 'x-api-key: <TOKEN>'

Response

{
  "id": "3Liye29ypHRGm4pvdLWuUt",
  "accountId": "gyTCZPpSbGZTBAFRa5Kgqo",
  "category": "token",
  "type": "centrapay.token.main",
  "liveness": "main",
  "description": "Centrapay Token",
  "createdAt": "2024-04-23T22:11:57.158Z",
  "status": "active",
  "currency": "NZD",
  "balance": "1234",
  "initialBalance": "5678",
  "availableBalance": "4321",
  "settlement": true,
  "approvalId": "mX5BUsewoTPExN1kWNjoqn",
  "expiresAt": "2024-05-07T22:11:56.924Z",
  "activeFrom": "2024-04-23T22:11:56.924Z",
  "bankAccountId": "KMHxO6dF38nbbJJSCGgCWR",
  "name": "token",
  "period": "month",
  "periodStartedAt": "2024-05-07T22:11:56.924Z",
  "periodEndingAt": "2024-05-09T22:11:56.924Z"
}

Asset Model

Attributes

id

accountId

category

type

liveness

description

createdAt

status

meta

name

Money Model

Attributes

currency

balance

availableBalance

settlement

period

periodStartedAt

periodEndingAt

Token Model experimental

Attributes

collectionId

createdBy

activeFrom

expiresAt

img

issuer

issuerWebsite

issuerImg

externalId

Ledger Model experimental

Attributes

collectionId

collectionType

tokenValue

createdBy

expiresAt

balanceExpiresAfter

img

issuerAccountId

balance

Get Asset

Get Asset Summary

List Assets for Account

Attributes

externalId

Archive Asset

Errors

UNSUPPORTED_ASSET_TYPE

Get Asset by External Id