The Popup Reward Store API

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/transactions

Authentication: Bearer token required

Query Parameters

ParameterTypeDefaultDescription
pagenumber1Page number for pagination (min: 1)
limitnumber50Number of items per page (min: 1, max: 10,000)
sortobject{"field":"id","direction":"DESC"}Sort configuration
currencystring-Filter by currency
namestring-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: true

Response 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

FieldTypeDescription
idnumberUnique transaction identifier
wallet_idnumberAssociated wallet ID
currency_idnumberCurrency ID for the transaction
amountnumberTransaction amount (positive for credits, negative for debits)
transaction_typestringType of transaction: "CREDIT" or "DEBIT"
statusstringCurrent transaction status
source_currencystringSource currency code for forex transactions (omitted if not applicable)
destination_currencystringDestination currency code for forex transactions (omitted if not applicable)
forex_ratenumberExchange rate applied (omitted if not applicable)
conversion_chargesnumberCharges for currency conversion (omitted if not applicable)
remarksstringTransaction description or notes
created_atstringTransaction timestamp in RFC3339 format

Pagination Headers

HeaderDescription
X-PageCurrent page number
X-Per-PageItems per page
X-Total-CountTotal number of transactions
X-Total-PagesTotal number of pages
X-Page-SizeActual items in current page
X-Has-MoreWhether 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/:id

Authentication: Bearer token required

Path Parameters

ParameterTypeRequiredDescription
idnumberYesUnique 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):

FieldDescription
source_currencyOriginal currency code (e.g., "USD")
destination_currencyTarget currency code (e.g., "EUR")
forex_rateExchange rate applied
conversion_chargesFee 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