User Transactions

Flow Summary

The current mobile user transaction flow is:

Step 1. Load your transaction list
GET /api/v1/mobile_user/transactions

Step 2. Open one transaction detail
GET /api/v1/mobile_user/transactions/{id}

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

Authorization: Bearer <access_token>

Data Model Notes

These routes read from mobile_user_transactions.

Important current behavior:

• The handler always forces the list to the authenticated mobile_user_id
• The list query excludes FAILED rows at the repository level
• amount is returned as a formatted string with 2 decimals, even though the database stores it as an integer amount
• payment_number is a 9-digit zero-padded sequence such as 000000123

1. List Transactions

GET /api/v1/mobile_user/transactions

Returns a paginated list of transactions for the authenticated mobile user.

Query parameters

Common current values

• transaction_type often includes:
  • TOP_UP
  • WITHDRAW
  • TRANSFER
  • RECEIVE
  • CARD_REQUEST
• transaction_status commonly includes:
  • PENDING
  • SUCCESS
  • FAILED
• direction uses:
  • IN
  • OUT

Important backend behavior

• The handler rejects the request if start_date > end_date
• The repository excludes FAILED rows before any other filters are applied
• Because of that exclusion, filtering with transaction_status=FAILED currently returns no rows
• If page < 1, the repository normalizes it to 1
• If limit < 1, the repository normalizes it to 20

Success response shape

{
  "status_code": 200,
  "message": "Transactions retrieved successfully",
  "data": [
    {
      "id": 91,
      "uuid": "0d65f58d-47f6-43d7-84b2-4bdc8d44e391",
      "payment_number": "000000091",
      "order_id": "ORD-20260228-H3KZ",
      "card_id": 508,
      "transaction_type": "TOP_UP",
      "amount": "100.00",
      "direction": "IN",
      "transaction_status": "SUCCESS",
      "transaction_currency": "USD",
      "merchant": "",
      "transfer_id": null,
      "created_at": "2026-02-28T10:00:00Z",
      "updated_at": "2026-02-28T10:00:00Z"
    }
  ],
  "metadata": {
    "current_page": 1,
    "limit": 20,
    "total": 1
  }
}

Notes

• The list response does not expand transfer source/destination card details
• For transfer enrichment, open the detail endpoint below

2. Get Transaction By ID

GET /api/v1/mobile_user/transactions/{id}

Returns one transaction by local numeric transaction ID.

Important backend behavior

• The row is loaded first by local id
• The service then verifies that transaction.mobile_user_id matches the authenticated user
• If the row belongs to another user, the API returns a not-found style response

Transfer-specific enrichment

If the transaction has a non-zero transfer_id, the service also loads the linked card transfer and adds:

• source_card_uuid
• source_card_number
• source_card_holder_name
• destination_card_uuid
• destination_card_number
• destination_card_holder_name
• remark

Important caveat

• If a transaction has transfer_id > 0 but the linked transfer row can no longer be loaded, the detail endpoint returns an error even though the base transaction exists

Success response shape

{
  "status_code": 200,
  "message": "Transaction retrieved successfully",
  "data": {
    "id": 92,
    "transaction_type": "TRANSFER",
    "amount": "25.50",
    "direction": "OUT",
    "transaction_status": "SUCCESS",
    "source_card_uuid": "5e5d4990-2241-46dc-9dbd-8abcf97e6061",
    "destination_card_uuid": "6f77454d-400f-4ec4-8e2c-7a7ebfa0bcfe",
    "remark": "Split payment"
  }
}

Integration Notes

1. Use this module for the app's own transaction timeline, not for raw card-network transaction history.
2. Use Card Transaction History when you need the underlying card transaction feed.
3. Use the detail endpoint for transfer rows when you need source/destination card context.