Go to home page
Docs

Wallets

A Wallet is an Asset that represents Money. The Wallet maintains a record of all transactions it has participated in. A Wallet has a single balance and a single currency.

Settlement Wallets experimental

A Settlement Wallet is a special type of Wallet that can only receive or refund money related to a Payment Request. This means you cannot topup, withdraw, or send money from this Wallet.

Wallet Model

Attributes

  • id

    string

    The unique identifier of the Wallet.

  • accountId

    string

    The Wallets’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

    Timestamp at which the Wallet was created.

  • status

    string

    active if the Wallet can be used for payments.

  • 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

    true if the Wallet is a Settlement Wallet.

Wallet Transaction Model

Attributes

  • activityNumber

    bignumber

    Unique sequential Wallet transaction number.

  • amount

    bignumber

    Absolute transaction amount in cents.

  • value

    bignumber

    Change to the Wallet’s balance in cents when the transaction was applied.

  • createdAt

    timestamp

    Transaction timestamp as ISO 8601 date string.

  • activityType

    string

    Hints to the type of transaction: undefined or returned-asset-transfer.

  • destWalletId

    string

    Id of the destination Wallet if applicable.

  • srcWalletId

    string

    Id of the source Wallet if applicable.

  • destParty

    string

    Display value for party receiving funds if applicable. Values may include a merchant name, user handle, masked user email, masked user phone, or bank account.

  • srcParty

    string

    Display value for party providing funds if applicable. Values may include a merchant name, user handle, masked user email, masked user phone, or bank account.

  • paymentRequestId

    string

    Unique identifier of the related Payment Request if applicable.

  • topupId

    string

    Unique identifier of the related topup Funds Transfer request if applicable.

  • assetTransferId

    string

    Unique identifier of the related Asset Transfer request if applicable.

  • withdrawalId

    string

    Unique identifier of the related Withdrawal request if applicable.

POST /api/wallets

Create a Wallet

This endpoint allows you to create a Wallet.

Attributes

  • accountId

    string required

    The Wallets’s owning Centrapay Account id.

  • ledgerId

    string required

    Asset Type id used by payment option asset types.

  • settlement

    boolean experimental

    true if the Wallet is a Settlement Wallet.

Errors

  • ACCOUNT_MAX_WALLETS_REACHED

    403

    The maximum number of wallets for the given ledger has been reached.

Request
curl -X POST \
 https://service.centrapay.com/api/wallets \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
 "ledgerId": "centrapay.nzd.main",
 "settlement": "true"
}
'
Response
{
  "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": "0",
  "availableBalance": "6000",
  "settlement": true
}
GET /api/wallets

List Wallets

This endpoint allows you to list authorized Wallets.

Request
curl -X GET \
 https://service.centrapay.com/api/wallets \
 -H 'x-api-key: <TOKEN>'
Response
[
  {
    "id": "WRhAxxWpTKb5U7pXyxQjjY",
    "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
    "ledgerId": "centrapay.nzd.main",
    "currency": "NZD",
    "balance": "2000",
    "availableBalance": "6000"
  },
  {
    "id": "NQ1yeromwnWPD2hY41L2yS",
    "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
    "ledgerId": "centrapay.nzd.test",
    "currency": "NZD",
    "balance": "20",
    "availableBalance": "6000"
  }
]
GET /api/wallets/{walletId}/transactions

List Wallet Transactions

This endpoint allows you to list Wallet Transactions.

Request
curl -X GET \
 https://service.centrapay.com/api/wallets/WRhAxxWpTKb5U7pXyxQjjY/transactions \
 -H 'x-api-key: <TOKEN>'
Response
{
  "items": [
    {
      "activityNumber": "1",
      "amount": "5000",
      "value": "5000",
      "createdAt": "2020-06-17T18:00:23.000Z",
      "srcParty": "12-4000-100001-00",
      "destWalletId": "EBVSreNmpsE2Pazw3SipXC",
      "topupId": "77hqHDzw6KaaG2P2hoshUB"
    }
  ]
}