Getgiftcardtransactions

Get Gift Card Transaction History

Retrieves paginated transaction history for a gift card with complete audit trail. Transactions include all card activities: activation, reloads, redemptions, and consolidations.

Transaction Types:

• ACTIVATION: Initial card activation and balance loading
• RELOAD: Balance addition transactions
• REDEMPTION: Balance deduction for purchases (negative amount)
• CONSOLIDATION: Card consolidation (negative for voided cards, positive for new card)
• VOID: Card voiding transactions
• PURCHASE: Gift card purchase transactions
• REFUND: Refund credit transactions

Business Rules:

• Returns transactions in reverse chronological order (newest first)
• Includes before/after balance for each transaction
• Contains optional POS reference data (transactionId, cashierId, terminalId)
• Supports pagination for large transaction histories
• All transactions immutable for audit compliance

Path Parameters:

• programId: MongoDB ObjectId of the loyalty program
• cardId: MongoDB ObjectId of the gift card

Query Parameters:

• limit: Maximum number of transactions to return (1-100, default: 50)
• offset: Number of transactions to skip for pagination (default: 0)

Returns:

• List of transaction objects ordered by createdAt (newest first)
• Each transaction includes full details: type, amount, balances, timestamps, references

Transaction Response Fields:

{
    "id": "507f1f77bcf86cd799439011",
    "transactionType": "REDEMPTION",
    "amount": -25.50,
    "balanceBefore": 100.00,
    "balanceAfter": 74.50,
    "referenceId": "ORDER_12345",
    "description": "Purchase at Store #42",
    "createdAt": "2025-01-15T10:30:00Z",
    "processedAt": "2025-01-15T10:30:00Z",
    "merchantId": "merchant_123",
    "posTransactionId": "POS_TXN_789",
    "cashierId": "cashier_001",
    "terminalId": "terminal_A"
}

Status Codes:

• 200: Transactions retrieved successfully (empty list if no transactions)
• 404: Gift card not found or doesn’t belong to program
• 401: Unauthorized

Pagination Example:

• First page: /giftcards/programs/{programId}/cards/{id}/transactions?limit=20&offset=0
• Second page: /giftcards/programs/{programId}/cards/{id}/transactions?limit=20&offset=20
• Third page: /giftcards/programs/{programId}/cards/{id}/transactions?limit=20&offset=40