Retrieve wallet information and manage multi-currency balances for client accounts

Wallets API

The Wallets API provides access to client wallet information, enabling balance queries and wallet listing for multi-currency transaction management.

List Wallets

Retrieve a paginated list of wallets for the authenticated client.

Endpoint

GET /api/v1/wallets

Authentication: Bearer token required

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number for pagination (min: 1)
`limit`	number	50	Number of items per page (min: 1, max: 10,000)
`currency`	string	-	Filter by currency
`name`	string	-	Filter by name

Note: Wallets are always sorted by ID in descending order (newest first). The sort query parameter is not supported for this endpoint.

Response

Success Response (200 OK)

Headers:

X-Page: 1
X-Per-Page: 50
X-Total-Count: 5
X-Total-Pages: 1
X-Page-Size: 5
X-Has-More: false

Response Body:

[
  {
    "id": 101,
    "currency_id": 1,
    "amount": 5000.00,
    "type": "PREPAID"
  },
  {
    "id": 102,
    "currency_id": 2,
    "amount": 2500.50,
    "type": "PREPAID"
  },
  {
    "id": 103,
    "currency_id": 3,
    "amount": 10000.00,
    "type": "POSTPAID"
  }
]

Response Fields

Field	Type	Description
`id`	number	Unique wallet identifier
`currency_id`	number	Associated currency ID
`amount`	number	Current wallet balance
`type`	string	Wallet type ("PREPAID" or "POSTPAID")

Pagination Headers

Header	Description
`X-Page`	Current page number
`X-Per-Page`	Items per page
`X-Total-Count`	Total number of wallets
`X-Total-Pages`	Total number of pages
`X-Page-Size`	Actual items in current page
`X-Has-More`	Whether more pages are available

Error Responses

400 Bad Request

{
  "error": {
    "name": "BadRequestError",
    "code": "BAD_REQUEST",
    "message": "Invalid query parameters"
  }
}

401 Unauthorized

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Authentication required or failed."
  }
}

500 Internal Server Error

{
  "error": {
    "name": "InternalServerError",
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Could not retrieve wallets"
  }
}

Examples

# List all wallets
curl -X GET "{{host}}/api/v1/wallets" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# List wallets with pagination
curl -X GET "{{host}}/api/v1/wallets?limit=10&page=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

<?php
function listWallets($token, $limit = 50, $page = 1) {
    $params = ['limit' => $limit, 'page' => $page];

    $url = '{{host}}/api/v1/wallets?' . http_build_query($params);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $token,
            'Accept: application/json'
        ]
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// Usage
$wallets = listWallets('YOUR_ACCESS_TOKEN');
foreach ($wallets as $wallet) {
    echo "Wallet #{$wallet['id']}: {$wallet['amount']}\n";
}
?>

Get Wallet by ID

Retrieve detailed information for a specific wallet including current balance.

Endpoint

GET /api/v1/wallets/:id

Authentication: Bearer token required

Path Parameters

Parameter	Type	Required	Description
`id`	number	Yes	Unique wallet identifier

Response

Success Response (200 OK)

{
  "id": 101,
  "currency_id": 1,
  "amount": 5000.00,
  "type": "PREPAID"
}

Response Fields

Field	Type	Description
`id`	number	Unique wallet identifier
`currency_id`	number	Associated currency ID
`amount`	number	Current wallet balance (precision based on currency)
`type`	string	Wallet type ("PREPAID" or "POSTPAID")

Error Responses

400 Bad Request

{
  "error": {
    "name": "BadRequestError",
    "code": "BAD_REQUEST",
    "message": "Invalid wallet ID"
  }
}

404 Not Found

{
  "error": {
    "name": "NotFoundError",
    "code": "NOT_FOUND",
    "message": "Wallet not found"
  }
}

500 Internal Server Error

{
  "error": {
    "name": "InternalServerError",
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Failed to retrieve wallet"
  }
}

Examples

curl -X GET "{{host}}/api/v1/wallets/101" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

<?php
function getWallet($token, $walletId) {
    $url = '{{host}}/api/v1/wallets/' . $walletId;

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $token,
            'Accept: application/json'
        ]
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 404) {
        throw new Exception("Wallet not found");
    }

    return json_decode($response, true);
}

// Usage
try {
    $wallet = getWallet('YOUR_ACCESS_TOKEN', 101);
    echo "Wallet ID: {$wallet['id']}\n";
    echo "Balance: {$wallet['amount']}\n";
    echo "Type: {$wallet['type']}\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

Implementation Notes

Balance Precision

Wallet balances are returned with precision appropriate to the currency:

Fiat currencies: 2 decimal places (e.g., USD: 100.50)
Zero-decimal currencies: No decimal places (e.g., JPY: 1000)

Wallet Types

PREPAID Wallets

Pre-funded wallet type for purchases
Requires balance to be loaded before making purchases
Real-time balance deduction on purchase

POSTPAID Wallets

Credit-based wallet type allowing purchases on credit
Transactions allowed up to configured credit limit
Balance can be negative up to the credit limit
Requires periodic settlement/payment

Security Considerations

Clients can only access their own wallets
Wallet IDs are globally unique
Balances are calculated in real-time from transaction ledger
All operations are atomic to prevent race conditions

Wallets API

On this page