Card Transaction

Flow Summary

The current transaction-history flow is:

Step 1. Make sure a cardholder already exists
Use Cardholder first

Step 2. Load either all your card activity or one card's activity
Use GET /api/v1/card-transactions/my-transactions or GET /api/v1/card-transactions/card/{card_id}

Step 3. Open a single transaction if needed
GET /api/v1/card-transactions/{id}

All routes below should be treated as protected routes and sent with:

Authorization: Bearer <access_token>

1. List Card Transactions

GET /api/v1/card-transactions

Returns a paginated list of stored card transaction rows with optional filters.

Query parameters

Important backend caveat

• The current handler binds the query directly and does not inject the authenticated user ID
• This means the route behaves like a broad reporting endpoint, not an automatically user-scoped list
• If the client needs a user-safe default, prefer GET /api/v1/card-transactions/my-transactions

2. Get Transaction By ID

GET /api/v1/card-transactions/{id}

Returns one stored card transaction by local numeric ID.

Important backend caveat

• The current service/repository reads by local row ID only
• There is no explicit ownership check in this handler path
• Treat this as an implementation gap until the backend adds a user scope

3. Get Transactions By Card ID

GET /api/v1/card-transactions/card/{card_id}

Returns transactions for one specific card.

Notes

• card_id here is the card ID string stored in the transaction table, not the local numeric card row ID
• Supports the same pagination, filter, and sort query params as the list endpoint, except mobile_user_id
• The current repository filters by card_id only and does not add an ownership check by user

4. Get Current User Transactions

GET /api/v1/card-transactions/my-transactions

Returns all stored card transactions for the authenticated user's linked cardholder.

Important backend behavior

• This is the safest user-facing history endpoint in the current implementation
• The handler reads the authenticated mobile_user_id, then loads the user's cardholder_id
• If the user has no linked cardholder_id, the API returns not found
• The repository then filters by cardholder_id, which covers all cards under that cardholder

Response shape

These endpoints return stored transaction rows, commonly including:

• local id and uuid
• transaction_id and short_transaction_id
• card_id, card_number, cardholder_id
• amount fields such as trans_amount, billing_amount, transaction_fee
• transaction_type and transaction_status
• transaction_time, posted_time, complete_time
• merchant fields such as merchant_name, merchant_category, merchant_country
• webhook metadata such as event_name, event_type, and processed_at