Transactions API
Query wallet transaction history and retrieve detailed transaction information
Transactions API
The Transactions API provides access to wallet transaction history, enabling you to retrieve transaction details and track all wallet activities including credits, debits, and forex conversions.
List Transactions
Retrieve a paginated list of transactions for the authenticated client.
Endpoint
GET /api/v1/transactionsAuthentication: 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) |
sort | object | {"field":"id","direction":"DESC"} | Sort configuration |
currency | string | - | Filter by currency |
name | string | - | Filter by name |
Sort Object Format
{
"field": "id",
"direction": "DESC"
}Response
Success Response (200 OK)
Headers:
X-Page: 1
X-Per-Page: 50
X-Total-Count: 150
X-Total-Pages: 3
X-Page-Size: 50
X-Has-More: trueResponse Body:
[
{
"id": 1001,
"wallet_id": 101,
"currency_id": 1,
"amount": 500.00,
"transaction_type": "CREDIT",
"status": "COMPLETED",
"remarks": "Wallet funding via bank transfer",
"created_at": "2025-01-15T10:30:00Z"
},
{
"id": 1002,
"wallet_id": 101,
"currency_id": 1,
"amount": -25.00,
"transaction_type": "DEBIT",
"status": "COMPLETED",
"remarks": "Order #12345 - Amazon Gift Card",
"created_at": "2025-01-15T11:45:00Z"
},
{
"id": 1003,
"wallet_id": 102,
"currency_id": 2,
"amount": 100.00,
"transaction_type": "CREDIT",
"status": "COMPLETED",
"source_currency": "USD",
"destination_currency": "EUR",
"forex_rate": 0.92,
"conversion_charges": 2.50,
"remarks": "Forex conversion from USD wallet",
"created_at": "2025-01-15T12:00:00Z"
}
]Response Fields
| Field | Type | Description |
|---|---|---|
id | number | Unique transaction identifier |
wallet_id | number | Associated wallet ID |
currency_id | number | Currency ID for the transaction |
amount | number | Transaction amount (positive for credits, negative for debits) |
transaction_type | string | Type of transaction: "CREDIT" or "DEBIT" |
status | string | Current transaction status |
source_currency | string | Source currency code for forex transactions (omitted if not applicable) |
destination_currency | string | Destination currency code for forex transactions (omitted if not applicable) |
forex_rate | number | Exchange rate applied (omitted if not applicable) |
conversion_charges | number | Charges for currency conversion (omitted if not applicable) |
remarks | string | Transaction description or notes |
created_at | string | Transaction timestamp in RFC3339 format |
Pagination Headers
| Header | Description |
|---|---|
X-Page | Current page number |
X-Per-Page | Items per page |
X-Total-Count | Total number of transactions |
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": "Failed to retrieve transactions"
}
}Examples
# Get first page of transactions
curl -X GET "{{host}}/api/v1/transactions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# Get transactions with custom pagination
curl -X GET "{{host}}/api/v1/transactions?limit=20&page=1" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# Sort by amount ascending
curl -X GET "{{host}}/api/v1/transactions?sort=%7B%22field%22%3A%22amount%22%2C%22direction%22%3A%22ASC%22%7D" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"<?php
function listTransactions($token, $limit = 50, $page = 1) {
$params = [
'page' => $page,
'limit' => $limit
];
$url = '{{host}}/api/v1/transactions?' . http_build_query($params);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Accept: application/json'
],
CURLOPT_HEADER => true
]);
$response = curl_exec($ch);
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers = substr($response, 0, $headerSize);
$body = substr($response, $headerSize);
curl_close($ch);
// Parse pagination headers
$pagination = [];
if (preg_match('/X-Page: (\d+)/', $headers, $matches)) {
$pagination['current_page'] = (int)$matches[1];
}
if (preg_match('/X-Total-Count: (\d+)/', $headers, $matches)) {
$pagination['total_count'] = (int)$matches[1];
}
if (preg_match('/X-Total-Pages: (\d+)/', $headers, $matches)) {
$pagination['total_pages'] = (int)$matches[1];
}
return [
'transactions' => json_decode($body, true),
'pagination' => $pagination
];
}
// Example: Get recent transactions
$result = listTransactions('YOUR_ACCESS_TOKEN', 20, 1);
foreach ($result['transactions'] as $txn) {
echo "Transaction #{$txn['id']}: {$txn['amount']}\n";
echo " Type: {$txn['transaction_type']}\n";
echo " Status: {$txn['status']}\n";
echo " Date: {$txn['created_at']}\n\n";
}
echo "Page {$result['pagination']['current_page']} of {$result['pagination']['total_pages']}\n";
echo "Total transactions: {$result['pagination']['total_count']}\n";
?>Get Transaction by ID
Retrieve detailed information for a specific transaction including all forex conversion details and charges.
Endpoint
GET /api/v1/transactions/:idAuthentication: Bearer token required
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | number | Yes | Unique transaction identifier |
Response
Success Response (200 OK)
{
"id": 1003,
"wallet_id": 102,
"currency_id": 2,
"amount": 100.00,
"transaction_type": "CREDIT",
"status": "COMPLETED",
"source_currency": "USD",
"destination_currency": "EUR",
"forex_rate": 0.92,
"conversion_charges": 2.50,
"remarks": "Forex conversion from USD wallet",
"created_at": "2025-01-15T12:00:00Z"
}Response Fields
Same as the List Transactions response fields.
Error Responses
400 Bad Request
{
"error": {
"name": "BadRequestError",
"code": "BAD_REQUEST",
"message": "Invalid transaction ID"
}
}404 Not Found
{
"error": {
"name": "NotFoundError",
"code": "NOT_FOUND",
"message": "Transaction not found"
}
}500 Internal Server Error
{
"error": {
"name": "InternalServerError",
"code": "INTERNAL_SERVER_ERROR",
"message": "Failed to retrieve transaction"
}
}Examples
curl -X GET "{{host}}/api/v1/transactions/1003" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"<?php
function getTransaction($token, $transactionId) {
$url = '{{host}}/api/v1/transactions/' . $transactionId;
$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("Transaction not found");
}
return json_decode($response, true);
}
// Usage
try {
$transaction = getTransaction('YOUR_ACCESS_TOKEN', 1003);
echo "Transaction ID: {$transaction['id']}\n";
echo "Amount: {$transaction['amount']}\n";
echo "Type: {$transaction['transaction_type']}\n";
echo "Status: {$transaction['status']}\n";
// Display forex details if present
if ($transaction['forex_rate']) {
echo "Forex Rate: {$transaction['forex_rate']}\n";
echo "Conversion Charges: {$transaction['conversion_charges']}\n";
echo "From: {$transaction['source_currency']}\n";
echo "To: {$transaction['destination_currency']}\n";
}
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}
?>Implementation Notes
Transaction Amount Convention
- CREDIT transactions: Positive amounts (e.g., 500.00)
- DEBIT transactions: Negative amounts (e.g., -25.00)
- The amount sign indicates the direction of funds relative to the wallet
Forex Transactions
When a transaction involves currency conversion, the following additional fields are included in the response (they are omitted for non-forex transactions):
| Field | Description |
|---|---|
source_currency | Original currency code (e.g., "USD") |
destination_currency | Target currency code (e.g., "EUR") |
forex_rate | Exchange rate applied |
conversion_charges | Fee charged for conversion |
Transaction Remarks
The remarks field contains contextual information about the transaction:
- Order payments: "Order #12345 - Product Name"
- Wallet funding: "Wallet funding via bank transfer"
- Refunds: "Refund for Order #12345"
- Forex conversions: "Forex conversion from USD wallet"
Next Steps
- Wallet Management - View wallet balances and details
- Order Tracking - Monitor order-related transactions