Wallet Management
This page covers wallet lifecycle operations: creating wallets, retrieving wallet details, checking balances, and fetching transaction history.
Create a Wallet
Endpoint
POST https://{FQDN}/wallets
Headers:
| Header | Value |
|---|
Authorization | Bearer {accessToken} |
Content-Type | application/json |
Request
| Field | Type | Required | Description |
|---|
accountAsset | string | ❌ | Currency or asset code for the wallet (e.g., "USD", "BRL") |
ownerId | string | ❌ | Identifier for the wallet owner |
beneficiaryId | string | ❌ | Identifier for the beneficiary |
type | string | ❌ | Wallet type (e.g., "PERSONAL", "BUSINESS") |
additionalInfo | object | ❌ | Arbitrary metadata to attach to the wallet |
Example Request
curl -X POST https://{FQDN}/wallets \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
-H 'Content-Type: application/json' \
-d '{
"accountAsset": "USD",
"ownerId": "user-12345",
"beneficiaryId": "user-12345",
"type": "PERSONAL"
}'
Response (200)
{
"walletId": "w-a1b2c3d4-e5f6-7890",
"accountAsset": "USD",
"ownerId": "user-12345",
"beneficiaryId": "user-12345",
"type": "PERSONAL",
"status": "ACTIVE",
"createdAt": "2025-03-31T10:00:00Z"
}
Get Wallet Details
Endpoint
GET https://{FQDN}/wallets/{walletId}
Headers:
| Header | Value |
|---|
Authorization | Bearer {accessToken} |
Path Parameters
| Parameter | Type | Required | Description |
|---|
walletId | string | ✅ | The wallet identifier |
Example Request
curl -X GET https://{FQDN}/wallets/w-a1b2c3d4-e5f6-7890 \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
Response (200)
{
"walletId": "w-a1b2c3d4-e5f6-7890",
"accountAsset": "USD",
"ownerId": "user-12345",
"beneficiaryId": "user-12345",
"type": "PERSONAL",
"status": "ACTIVE",
"createdAt": "2025-03-31T10:00:00Z"
}
Get Wallet Balance
Endpoint
GET https://{FQDN}/wallets/{walletId}/balance
Headers:
| Header | Value |
|---|
Authorization | Bearer {accessToken} |
Path Parameters
| Parameter | Type | Required | Description |
|---|
walletId | string | ✅ | The wallet identifier |
Example Request
curl -X GET https://{FQDN}/wallets/w-a1b2c3d4-e5f6-7890/balance \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
Response (200)
{
"walletId": "w-a1b2c3d4-e5f6-7890",
"accountAsset": "USD",
"availableBalance": 1250.75,
"heldBalance": 200.00,
"totalBalance": 1450.75
}
| Field | Type | Description |
|---|
availableBalance | number | Funds available for transactions |
heldBalance | number | Funds reserved by pending holds |
totalBalance | number | Sum of available and held balances |
Get Wallet Statement
Retrieve a paginated transaction history for a wallet, with optional date-range filtering.
Endpoint
GET https://{FQDN}/wallets/{walletId}/statement
Headers:
| Header | Value |
|---|
Authorization | Bearer {accessToken} |
Path Parameters
| Parameter | Type | Required | Description |
|---|
walletId | string | ✅ | The wallet identifier |
Query Parameters
| Parameter | Type | Required | Description |
|---|
from | string | ❌ | Start date (ISO 8601, e.g., "2025-03-01") |
until | string | ❌ | End date (ISO 8601, e.g., "2025-03-31") |
page | integer | ❌ | Page number (zero-based) |
size | integer | ❌ | Results per page |
Example Request
curl -X GET 'https://{FQDN}/wallets/w-a1b2c3d4-e5f6-7890/statement?from=2025-03-01&until=2025-03-31&page=0&size=20' \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
Response (200)
{
"walletId": "w-a1b2c3d4-e5f6-7890",
"entries": [
{
"transactionId": "txn-001",
"externalId": "order-5001",
"type": "CREDIT",
"amount": 500.00,
"description": "Wallet top-up",
"balanceAfter": 1450.75,
"createdAt": "2025-03-15T14:30:00Z"
},
{
"transactionId": "txn-002",
"externalId": "order-5002",
"type": "DEBIT",
"amount": 49.25,
"description": "Payment to merchant",
"balanceAfter": 1401.50,
"createdAt": "2025-03-16T09:15:00Z"
}
],
"page": 0,
"size": 20,
"totalEntries": 2
}
What's Next
