Go to home page
Docs API Reference

Assets

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 , withdrawn to a bank account via Funds Transfers and sent to other Centrapay users via Asset Transfers .

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

    object experimental

    Additional data that may only appear in the Get Asset response.

  • name

    string experimental

    The name of the asset when created from an enduring payment consent . 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

    boolean experimental

    The asset is configured for Settlements .

  • period

    string experimental

    The period after which the balance will be reset. This field is only available on the quartz asset type. Possible values are daily, weekly, fortnightly, monthly or yearly.

  • periodStartedAt

    timestamp experimental

    Datetime when the current period was started. This field is only available on the quartz asset type.

  • periodEndingAt

    timestamp experimental

    Datetime when the current period will end. This field is only available on the quartz 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 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 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 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 Asset

Request
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 Asset Summary

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

List Assets for Account

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

Attributes

  • externalId

    string

    The asset identifier from the issuing system.

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

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
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 Asset by External Id

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