Get Transaction History

Warning

Testing Phase: This endpoint is currently in testing and not ready for production. API structure and responses may change.

This method retrieves the paginated transaction history for a player’s gamification coins. Use gateway.[msdomain]

Request (GET)

/gateway/coins/transactions/{version}/{brand_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true Brand identifier
x-auth-token header string true Player authentication token (extracted from request header)
page query int false Page number (default: 1, min: 1, max: 1000)
page_size query int false Number of items per page (default: 20, min: 1, max: 100)
transaction_type query string false Filter by transaction type (RECEIVED or REDEEMED)
start_date query string false Filter transactions from this date (ISO 8601 format)
end_date query string false Filter transactions until this date (ISO 8601 format)

Note: The player_id is automatically extracted from the x-auth-token header by the gateway and appended to the path when forwarding to the marketing service.

Query Parameter Examples:

?page=1&page_size=20
?transaction_type=REDEEMED
?start_date=2025-01-01T00:00:00Z&end_date=2025-01-31T23:59:59Z
?page=2&page_size=50&transaction_type=RECEIVED

Response

Status 200

{
  "status": "success",
  "data": {
    "transactions": [
      {
        "id": 123456,
        "transaction_type": "REDEEMED",
        "transaction_sub_type": "CASH_BONUS",
        "amount": "-100.00",
        "balance_before": "250.50",
        "balance_after": "150.50",
        "created_at": "2025-01-09T14:30:00Z",
        "source": "PLAYER_SHOP",
        "reference_id": 78910,
        "trigger_details": {
          "shop_item_id": "507f1f77bcf86cd799439011",
          "shop_item_name": "10 USD Cash Bonus"
        }
      },
      {
        "id": 123455,
        "transaction_type": "RECEIVED",
        "transaction_sub_type": "MANUAL",
        "amount": "50.00",
        "balance_before": "200.50",
        "balance_after": "250.50",
        "created_at": "2025-01-08T10:15:00Z",
        "source": "ADMIN_GRANT",
        "reference_id": null,
        "trigger_details": {
          "comment": "Customer satisfaction compensation"
        }
      },
      {
        "id": 123454,
        "transaction_type": "REDEEMED",
        "transaction_sub_type": "FRB",
        "amount": "-75.00",
        "balance_before": "275.50",
        "balance_after": "200.50",
        "created_at": "2025-01-07T18:45:00Z",
        "source": "PLAYER_SHOP",
        "reference_id": 54321,
        "trigger_details": {
          "shop_item_id": "507f1f77bcf86cd799439012",
          "shop_item_name": "50 Free Rounds on Starburst",
          "game_id": "starburst",
          "provider_id": "netent",
          "rounds": 50
        }
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_pages": 5,
      "total_items": 87
    }
  },
  "message": "Successfully retrieved transaction history"
}

Response Fields:

Transaction Object:
Field Type Description
id int64 Transaction identifier
transaction_type string Type of transaction: “RECEIVED” or “REDEEMED”
transaction_sub_type string Sub-type: “MANUAL”, “CASH_BONUS”, “FRB”, “PHYSICAL”, etc.
amount string Transaction amount (decimal, negative for REDEEMED)
balance_before string Balance before the transaction (decimal)
balance_after string Balance after the transaction (decimal)
created_at string Transaction timestamp (ISO 8601)
source string Trigger source (e.g., “PLAYER_SHOP”, “ADMIN_GRANT”, “SYSTEM”)
reference_id int64 Optional - Financial reference ID (e.g., bonus ID)
trigger_details object Optional - Additional transaction metadata
Pagination Object:
Field Type Description
page int Current page number
page_size int Number of items per page
total_pages int Total number of pages
total_items int Total number of transactions

Transaction Sub-Types:

  • RECEIVED Transactions:

    • MANUAL - Manually granted coins (admin/system)

  • REDEEMED Transactions:

    • CASH_BONUS - Redeemed cash bonus item
    • FRB - Redeemed free rounds bonus item
    • PHYSICAL - Redeemed physical item

Status 500

{
  "status": "error",
  "data": null,
  "message": "Failed to get transaction history"
}

Notes

  • Transactions are returned in reverse chronological order (newest first)
  • Invalid query parameters (page, page_size) will be ignored and defaults will be used
  • Date filters use inclusive ranges (start_date ≤ transaction.created_at ≤ end_date)
  • The trigger_details field contains context-specific information based on the transaction type
  • For REDEEMED transactions, reference_id typically contains the financial system reference (e.g., bonus ID for CASH_BONUS)