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