Link Search Menu Expand Document
Centrapay 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.

Contents

Creating a Wallet

POST /api/wallets 

curl -X POST https://service.centrapay.com/api/wallets \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
    "ledgerId": "centrapay.nzd.main"
  }'

Required Fields

Field Type Description
accountId String The id of the account
ledgerId String The id of the ledger e.g. centrapay.nzd.main, centrapay.nzd.test

Optional Fields

Field Type Description
settlement Boolean EXPERIMENTAL Configure the Wallet to be a Settlement Wallet.

Example response payload 

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

Example response payload for Settlement Wallet 

{
  "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",
  "settlement": true
}

Error Responses

Status Code Description
403 ACCOUNT_MAX_WALLETS_REACHED The maximum number of wallets for the given ledger has been reached.

Listing authorized wallets

GET /api/wallets 

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

Example response payload 

[
  {
    "id": "WRhAxxWpTKb5U7pXyxQjjY",
    "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
    "ledgerId": "centrapay.nzd.main",
    "currency": "NZD",
    "balance": "2000"
  },
  {
    "id": "NQ1yeromwnWPD2hY41L2yS",
    "accountId": "Te2uDM7xhDLWGVJU3nzwnh",
    "ledgerId": "centrapay.nzd.test",
    "currency": "NZD",
    "balance": "20"
  }
]

Listing Wallet Transactions EXPERIMENTAL

Returns a paginated list of Wallet Transactions.

GET /api/wallets/{walletId}/transactions 

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

Transaction Fields

Field Type Description
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. See note below.
srcParty String Display value for party providing funds if applicable. See note below.
paymentRequestId String Id of the related payment request if applicable.
topupId String Id of the related topup funds transfer request if applicable.
assetTransferId String Id of the related asset transfer request if applicable.
withdrawalId String Id of the related withdrawal request if applicable.

Party Values

The “destParty” and “srcParty” are optionally provided depending on the purpose of the transaction. Values may include a merchant name, user handle, masked user email, masked user phone, or bank account.

Example response payload (Payment) 

{
  "items": [
    {
      "activityNumber": "1",
      "amount": "350",
      "value": "-350",
      "createdAt": "2020-06-17T18:00:23.000Z",
      "destParty": "Centrapay Cafe",
      "destWalletId": "GfYJd5tZQ63CrehgTP2RPB",
      "srcWalletId": "EBVSreNmpsE2Pazw3SipXC",
      "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw"
    }
  ]
}

Example response payload (Topup) 

{
  "items": [
    {
      "activityNumber": "1",
      "amount": "5000",
      "value": "5000",
      "createdAt": "2020-06-17T18:00:23.000Z",
      "srcParty": "12-4000-100001-00",
      "destWalletId": "EBVSreNmpsE2Pazw3SipXC",
      "topupId": "77hqHDzw6KaaG2P2hoshUB"
    }
  ]
}

Example response payload (Sent Asset) 

{
  "items": [
    {
      "activityNumber": "1",
      "amount": "2500",
      "value": "-2500",
      "createdAt": "2020-06-17T18:00:23.000Z",
      "destParty": "+6422*****36",
      "srcWalletId": "EBVSreNmpsE2Pazw3SipXC",
      "assetTransferId": "TtQHufC4LGBY2eiPRopRm3"
    }
  ]
}

Example response payload (Received Asset) 

{
  "items": [
    {
      "activityNumber": "1",
      "amount": "2500",
      "value": "2500",
      "createdAt": "2020-06-17T18:00:23.000Z",
      "srcParty": "+6421*****18",
      "destWalletId": "EBVSreNmpsE2Pazw3SipXC",
      "assetTransferId": "TtQHufC4LGBY2eiPRopRm3"
    }
  ]
}

Example response payload (Returned Asset) 

{
  "items": [
    {
      "activityNumber": "1",
      "amount": "2500",
      "value": "2500",
      "createdAt": "2020-06-17T18:00:23.000Z",
      "activityType": "returned-asset-transfer",
      "srcParty": "+6421*****18",
      "destWalletId": "EBVSreNmpsE2Pazw3SipXC",
      "assetTransferId": "TtQHufC4LGBY2eiPRopRm3"
    }
  ]
}

Example response payload (Withdraw) 

{
  "items": [
    {
      "activityNumber": "1",
      "amount": "2500",
      "value": "2500",
      "createdAt": "2020-06-17T18:00:23.000Z",
      "srcWalletId": "EBVSreNmpsE2Pazw3SipXC",
      "destParty": "12-3546-2544786-00",
      "withdrawalId": "TtQHufC4LGBY2eiPRopRm3"
    }
  ]
}