Link Search Menu Expand Document

External Assets

External assets are Assets which are issued by a third-party.


Load an External Asset

Load an asset from a supported third-party issuer. Asset details will be obtained from the issuer.

POST /api/external-assets

curl -X POST \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "category": "giftcard",
    "type": "epay.nzd.test",
    "issuer": "ezipay",
    "externalId": "23403321042",
    "pin": "3771"

Required Fields

Parameter Type Description
accountId String The Centrapay account which will own the asset.
category String The category an asset will be grouped by. Valid values: “giftcard”.
type String The Centrapay ledger corresponding to the asset. Valid values: “epay.nzd.main”, “epay.nzd.test”.
issuer String The asset issuer. Valid values: “ezipay”.
externalId String The issuer’s asset id such as card number.

Optional Parameters

Parameter Type Description
pin String Additional secret required by the issuer for loading or redeeming the asset.
description String Description of the asset, eg: “$60 Acme Giftcard”.

Example response payload

  "id": "L75M3L56N2PtBSt8g7uXLU",
  "category": "giftcard",
  "type": "epay.nzd.main",
  "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
  "issuer": "ezipay",
  "externalId": "************60119",
  "description": "$60 Acme Giftcard",
  "productCode": "23403",
  "currency": "NZD",
  "initialBalance": "7000",
  "balance": "6000",
  "availableBalance": "6000",
  "balanceUpdatedAt": "2020-06-10T15:30:00.000Z",
  "expiresAt": "2020-12-31T00:00:00.000Z",
  "createdAt": "2020-05-01T12:30:00.000Z"

Error Responses

Status Code Description
403 UNKNOWN_ASSET Asset id or PIN is incorrect.
403 DUPLICATE_ASSET Asset already claimed by another account.
403 UNSUPPORTED_ASSET_TYPE Unsupported asset type, origin, or issuer.
403 DENIED_BY_ASSET_PROVIDER Asset exists, but is not enabled for use through centrapay.
403 EXPIRED_BY_ASSET_PROVIDER Asset exists, but it’s expired.