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  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, Gift Cards 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.

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


Gift cards are similar to money but have greater spending restrictions and are not always backed by real currency. Gift cards usually have an expiry date, are typically tied to a small number of merchants, and can only be sent in their entirety.

Gift cards have the following attributes along with the base asset fields.

Attributes

  • issuer

    string

    The identifier for the issuer of the gift card.

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

  • initialBalance

    bignumber

    The balance when the asset was created.

  • externalId

    string

    The asset identifier from the issuing system.

  • expiresAt

    timestamp

    The date when the asset expires.

  • balanceUpdatedAt

    timestamp

    The date when the balance was last observed to be updated.

  • productCode

    stringexperimental

    The unique code which must match a merchant’s payment option for redemption.

  • img

    stringexperimental

    The img URL of the gift card.

  • brandName

    stringexperimental

    The name of the brand that the gift card belongs to.

  • brandImg

    stringexperimental

    The img URL of the brand that the gift card belongs to.

  • brandWebsite

    stringexperimental

    The URL of the brand that the gift card belongs to.

  • issuerWebsite

    stringexperimental

    The URL of the issuer of the gift card.


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

  • issuerImg

    string

    The img URL of the issuer that the token belongs to.

  • externalId

    string

    The asset identifier from the issuing system.


GET/api/assets/{assetId}
Request
GET/api/assets/L75M3L56N2PtBSt8g7uXLU
curl -X GET \
 https://service.centrapay.com/api/assets/L75M3L56N2PtBSt8g7uXLU \
 -H 'x-api-key: <TOKEN>'
Response
{
  "id": "L75M3L56N2PtBSt8g7uXLU",
  "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
  "category": "giftcard",
  "type": "epay.nzd.main",
  "issuer": "ezipay",
  "externalId": "23403283262",
  "description": "$60 Acme Giftcard",
  "productCode": "23403",
  "initialBalance": "6000",
  "balance": "6000",
  "availableBalance": "6000",
  "balanceUpdatedAt": "2021-01-01T00:00:00.000Z",
  "expiresAt": "2020-12-31T00:00:00.000Z",
  "createdAt": "2020-05-01T12:30:00.000Z"
}

GET/api/assets/{assetId}/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

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": "L75M3L56N2PtBSt8g7uXLU",
      "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
      "category": "giftcard",
      "type": "epay.nzd.main",
      "issuer": "ezipay",
      "externalId": "23403283262",
      "description": "$60 Acme Giftcard",
      "productCode": "23403",
      "initialBalance": "6000",
      "balance": "6000",
      "availableBalance": "6000",
      "balanceUpdatedAt": "2021-01-01T00:00:00.000Z",
      "expiresAt": "2020-12-31T00:00:00.000Z",
      "createdAt": "2020-05-01T12:30:00.000Z"
    },
    {
      "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 supported asset types by asset id. Currently gift cards, tokens, and quartz.nzd assets may be archived.

Errors

  • UNSUPPORTED_ASSET_TYPE

    403

    Asset type can not be archived

Request
POST/api/assets/L75M3L56N2PtBSt8g7uXLU/archive
curl -X POST \
 https://service.centrapay.com/api/assets/L75M3L56N2PtBSt8g7uXLU/archive \
 -H 'x-api-key: <TOKEN>'
Response
{
  "id": "L75M3L56N2PtBSt8g7uXLU",
  "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
  "category": "giftcard",
  "type": "epay.nzd.main",
  "issuer": "ezipay",
  "externalId": "23403283262",
  "description": "$60 Acme Giftcard",
  "initialBalance": "6000",
  "balance": "0",
  "balanceUpdatedAt": "2021-01-01T00:00:00.000Z",
  "expiresAt": "2020-12-31T00:00:00.000Z",
  "createdAt": "2020-05-01T12:30:00.000Z",
  "status": "archived"
}