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 /
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",
"availableBalance": "6000"
}
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",
"availableBalance": "6000",
"settlement": true
}
Error Responses
Status | Code | Description |
---|---|---|
403 | ACCOUNT_ | The maximum number of wallets for the given ledger has been reached. |
Listing authorized wallets
GET /
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",
"availableBalance": "6000"
},
{
"id": "NQ1yeromwnWPD2hY41L2yS",
"accountId": "Te2uDM7xhDLWGVJU3nzwnh",
"ledgerId": "centrapay.nzd.test",
"currency": "NZD",
"balance": "20",
"availableBalance": "6000"
}
]
Listing Wallet Transactions EXPERIMENTAL
Returns a paginated list of Wallet Transactions.
GET /
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"
}
]
}