Card Transaction

Flow Summary

The current transaction-history flow is:

Step 1. Make sure the user already has an issued card
Use Card List 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>

Which Route Should You Use?

• Use GET /api/v1/card-transactions/my-transactions for the normal user transaction-history screen
• Use GET /api/v1/card-transactions/card/{card_id} when the user is already viewing one selected card
• Use GET /api/v1/card-transactions only when you intentionally need the broader reporting-style route
• Use GET /api/v1/card-transactions/{id} when you already have the local numeric transaction ID from a previous response

1. List Card Transactions

GET /api/v1/card-transactions

Returns a paginated list of 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
• If start_date is later than end_date, the API returns 400
• The underlying repository excludes rows where transaction_status = FAILED
• transaction_time is still accepted by the service as an alias, but it is normalized to created_at

2. Get Transaction By ID

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

Returns one card transaction by local numeric ID.

Important backend caveat

• The current service reads by local row ID only
• There is no explicit ownership check in this handler path
• If the row does not exist, the API returns 404
• This route is easiest to use when you already got the transaction id from a list response
• Treat the missing ownership check 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 card transactions for one specific card.

Notes

• card_id accepts either the external upstream card ID or the local numeric card row ID
• Supports the same pagination, filter, and sort query params as the list endpoint, except mobile_user_id
• Use payment_number when you want to search by payment number
• Use order_id when you want to search by order ID
• If the card cannot be resolved to a local card row, the API returns an empty list
• The current handler path still does not add an ownership check by authenticated user
• If start_date is later than end_date, the API returns 400
• This route is the better choice when the user has already selected one specific card in the UI

4. Get Current User Transactions

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

Returns card transactions for the authenticated user.

Important backend behavior

• This is the safest user-facing history endpoint in the current implementation
• Use this route as the default option for app transaction-history screens
• The handler reads the authenticated mobile_user_id and injects it into the list filter
• The route no longer depends on loading a cardholder_id first
• This route also accepts payment_number and order_id as direct filters
• The same date-range validation applies here, so start_date > end_date returns 400
• Sorting now defaults to created_at desc
• The underlying repository excludes rows where transaction_status = FAILED

Response shape

These endpoints now return the current card transaction payload instead of the older raw card webhook row.

Common fields include:

• id, uuid, payment_number, and order_id
• card_id, transaction_type, direction, and transaction_status
• amount, transaction_currency, transaction_amount, currency, transaction_fee, and transaction_fee_currency
• merchant, created_at, and updated_at
• title on list responses
• details on detail responses, plus transfer or withdrawal card metadata such as source_card_uuid, destination_card_uuid, and holder names when applicable