Get Wallet Transactions

Retrieve transaction history for a specific currency wallet.

List Transactions

GEThttps://api.zenpayz.com/merchant/api/v1/wallet/{currency}/transactions

Bearer · API key

Headers

Header	Description
Authorization REQUIRED	Bearer {api_key}
X-Signature REQUIRED	HMAC-SHA256 signature
X-Timestamp REQUIRED	ISO 8601 timestamp
X-Secret-Salt REQUIRED	Secret salt for HMAC validation

Path Parameters

Parameter	Type	Description
currency REQUIRED	string	ISO 4217 currency code for the wallet

Query Parameters

Parameter	Type	Description
page OPTIONAL	integer1	Page number
limit OPTIONAL	integer20	Items per page
startDate OPTIONAL	string-	Start date filter (ISO 8601)
endDate OPTIONAL	string-	End date filter (ISO 8601)
type OPTIONAL	string-	Filter by type (CREDIT, DEBIT, SETTLEMENT, COMMISSION, REFUND, CHARGEBACK)
status OPTIONAL	string-	Filter by status (PENDING, PROCESSING, COMPLETED, FAILED, REVERSED)
search OPTIONAL	string-	Search across transaction id, source transaction id, source order id, and amount-like fields

Response (200 OK)

{
  "success": true,
  "data": {
    "data": [
      {
        "transactionId": "wtx_xxxxx",
        "type": "CREDIT",
        "amount": 1000,
        "balanceBefore": 249000,
        "balanceAfter": 250000,
        "description": "Payment received",
        "sourceType": "PAYMENT",
        "sourceTransactionId": "txn_xxxxx",
        "sourceOrderId": "ord_xxxxx",
        "status": "COMPLETED",
        "processedAt": "2024-01-15T10:30:00.000Z",
        "settlementDate": "2024-01-16T00:00:00.000Z",
        "currency": "USD",
        "feeAmount": 0,
        "grossAmount": 1000,
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 500,
      "total_pages": 25,
      "has_next": true,
      "has_prev": false
    }
  }
}

---

Important Note

GET /merchant/api/v1/wallet/{currency}/transactions/{transactionId} is not currently exposed on the merchant wallet route surface. Use the list endpoint with filters/search.

Transaction Types

Type	Description
CREDIT	Money added to wallet
DEBIT	Money withdrawn from wallet
SETTLEMENT	Settlement to bank account
COMMISSION	Commission or fee
REFUND	Refund processed
CHARGEBACK	Chargeback deduction

Transaction Statuses

Status	Description
PENDING	Transaction initiated, awaiting processing
PROCESSING	Transaction being processed
COMPLETED	Transaction completed
FAILED	Transaction failed
REVERSED	Transaction reversed

Examples

cURL

# List wallet transactions
curl -X GET "https://api.zenpayz.com/merchant/api/v1/wallet/USD/transactions?type=CREDIT&limit=50&page=1&search=txn_123" \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: 2024-01-15T10:30:00.000Z" \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Secret-Salt: your_secret_salt"

SDK

// SDK currently provides a filter-based wallet transactions API.
// Use `currency` in filters to scope to one wallet.
const result = await zenpays.wallet.listTransactions({
  currency: 'USD',
  type: 'credit',
  limit: 50,
  page: 1,
});