Link Search Menu Expand Document

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

Contents

Models

Asset

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.

Fields

Field Type Description
id String The Asset’s unique identifier.
accountId String The Asset’s owning Centrapay Account id.
category String Optional 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 Optional EXPERIMENTAL Additional data that may only appear in the Get Asset response.

Money

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 fields along with the base asset fields.

Fields

Field Type Description
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 Optional EXPERIMENTAL The asset is configured for Settlements.

Gift Cards

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 fields along with the base asset fields.

Fields

Field Type Description
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 Optional The asset identifier from the issuing system.
expiresAt Timestamp Optional The date when the asset expires.
balanceUpdatedAt Timestamp Optional The date when the balance was last observed to be updated.
productCode String Optional EXPERIMENTAL The unique code which must match a merchant’s payment option for redemption.
img String Optional EXPERIMENTAL The img URL of the gift card.
brandName String Optional EXPERIMENTAL The name of the brand that the gift card belongs to.
brandImg String Optional EXPERIMENTAL The img URL of the brand that the gift card belongs to.
brandWebsite String Optional EXPERIMENTAL The URL of the brand that the gift card belongs to.
issuerWebsite String Optional EXPERIMENTAL The URL of the issuer of the gift card.

Tokens (EXPERIMENTAL)

Tokens are assets which can be spent only once. They are usually tied to a small set of merchants and have an expiry date. Token value may be set in multiple currencies and is the same for all tokens of the same type.

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

Fields

Field Type Description
value Array The Monetary Amounts representing the token’s nominal value in its supported currencies.
validFrom Timestamp Optional The date when the asset becomes spendable.
expiresAt Timestamp Optional The date when the asset expires.

Operations

Get Asset

GET /api/assets/{assetId}

curl https://service.centrapay.com/api/assets/L75M3L56N2PtBSt8g7uXLU \
  -H "X-Api-Key: $api_key"

Example response payload

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

List Assets for Account

Returns a paginated list of Assets for an account. This will only return active assets.

GET /api/accounts/{accountId}/assets

curl https://service.centrapay.com/api/accounts/Te2uDM7xhDLWGVJU3nzwnh/assets \
  -H "X-Api-Key: $api_key"

Example response payload

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

Listing Asset Transactions EXPERIMENTAL

Returns a paginated list of Asset Transactions. This endpoint is currently only supported for kete asset types.

GET /api/assets/{assetId}/transactions

curl https://service.centrapay.com/api/assets/WRhAxxWpTKb5U7pXyxQjjY/transactions \
  -H "X-Api-Key: $api_key"

Transaction Fields

Field Type Description
ref String ID of the Centrapay resource that initiated this transaction.
refType String Name of the Centrapay resource that initiated this transaction.
type String Type of the Asset Transaction. Supported values are increment-balance, decrement-balance and transfer.
kind String Human readable value indicating the reason for this transaction.
srcAssetId String Optional ID of the source asset if applicable.
destAssetId String Optional ID of the destination asset if applicable.
srcParty String Optional Display value for party providing funds if applicable. See note below.
destParty String Optional Display value for party receiving funds if applicable. See note below.
otherParty String Optional Display value for party providing or receiving funds if applicable. See note below.
amount String Amount of transaction in cents.
activityType String Indicating whether the asset gained or lost value. Supported types are value-in and value-out.
activityNumber String Unique sequential Asset transaction number.

Party Values

The “destParty” and “srcParty” are optionally provided only on transactions of type transfer. Values may include a merchant name, user handle, masked user email, masked user phone, or bank account.

The “otherParty” is optionally provided only on transactions of type increment-balance and decrement-balance. Values may include bank account number.

Example response payload

{
  "items": [
    {
      "ref": "adRGJqMyMhmGfnDXasRZ",
      "type": "transfer",
      "kind": "refund",
      "refType": "payment-request",
      "assetId": "WRhAxxWpTKb5U7pXyxQjjY",
      "srcParty": "Coffee Ltd",
      "destParty": "crn::user:5a3b1ba7-d01k-409f-ld0a-jd81k0ald",
      "createdAt": "2022-03-31T20:36:08.562Z",
      "createdBy": "crn::service:payments-api",
      "srcAssetId": "Jd9a89ZESjjCuUD9DJD9Al",
      "destAssetId": "WRhAxxWpTKb5U7pXyxQjjY",
      "amount": "2000",
      "activityType": "value-in",
      "activityNumber": "3"
    },
    {
      "ref": "adRGJqMyMhmGfnDXasRZ",
      "type": "transfer",
      "kind": "payment",
      "refType": "payment-request",
      "assetId": "WRhAxxWpTKb5U7pXyxQjjY",
      "srcParty": "crn::user:5a3b1ba7-d01k-409f-ld0a-jd81k0ald",
      "destParty": "Coffee Ltd",
      "createdAt": "2022-03-31T20:35:54.717Z",
      "createdBy": "crn::service:payments-api",
      "srcAssetId": "WRhAxxWpTKb5U7pXyxQjjY",
      "destAssetId": "Jd9a89ZESjjCuUD9DJD9Al",
      "amount": "3000",
      "activityType": "value-out",
      "activityNumber": "2"
    },
    {
      "ref": "H4SZKwMcU9VCmnGEqDA7Mn",
      "type": "increment-balance",
      "kind": "topup",
      "refType": "topup",
      "assetId": "WRhAxxWpTKb5U7pXyxQjjY",
      "createdAt": "2022-03-31T02:37:47.207Z",
      "createdBy": "crn::application:rhea",
      "destAssetId": "WRhAxxWpTKb5U7pXyxQjjY",
      "amount": "7600",
      "activityType": "value-in",
      "activityNumber": "1"
    }
  ]
}

Archive Asset

Archive supported asset types by asset id. Currently only gift cards may be archived.

POST /api/assets/{assetId}/archive

curl -X POST https://service.centrapay.com/api/assets/L75M3L56N2PtBSt8g7uXLU/archive \
  -H "X-Api-Key: $api_key"

Example response payload

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

Error Responses

Status Code Description
403 UNSUPPORTED_ASSET_TYPE Asset type can not be archived