Get a List of User Transactions

List user transactions

post

This API endpoint retrieves a paginated list of transactions for a specific user reference. It supports filtering by transaction types, time ranges, and provides cursor-based pagination for efficient data retrieval. The response includes detailed transaction information along with currency metadata and pagination controls.

Body

Request to list transactions

afterstringOptional

Cursor to paginate after (for forward pagination)

beforestringOptional

Cursor to paginate before (for backward pagination)

firstintegerOptional

Number of transactions to return

lastintegerOptional

Return the last N transactions (backward pagination)

time_rangestring · dateOptional

Time range filter - today, yesterday, this_week, this_month, last_month, last_24hrs

user_reference_idstringRequired

User reference identifier

Responses

200

Transaction list

application/json

Response containing transaction history with edges structure

total_countintegerRequired

Total number of transactions

422

Validation error - missing required fields or invalid user_reference_id format (only alphanumeric, hyphens, and underscores allowed)

application/json

post/v1/user/transactions

POST /v1/user/transactions HTTP/1.1
Host: gateway.stage.pay.io
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "first": 5,
  "time_range": "today",
  "transaction_types": [
    "Deposit",
    "Payout"
  ],
  "user_reference_id": "hub_player_2"
}

{
  "edges": [
    {
      "cursor": "MjAyNS0wOC0xNFQxNToyNDo1OVp8MzkwNmZjM2EtODk4My00OWY0LTk3OWMtYzhiYmYzZDhhMDJi",
      "inserted_at": "2025-08-14T15:24:59Z",
      "node": {
        "amount": "1.000000000000000000000000000000",
        "amount_usd": "0.989822010805417845",
        "completed_at": "2025-08-14T15:24:58Z",
        "correlation_key": "d2c2a8bd-4473-4ee8-8d09-7f072162aae3",
        "currency": {
          "code": "USDC",
          "currency_icon": "https://cdn.hub88.io/hub-wallet/USDC-ic.svg",
          "id": "c872e749-fd56-533e-b01f-de87ae38e7f1",
          "name": "USD Coin",
          "network": "Base Chain",
          "network_icon": "https://cdn.hub88.io/hub-wallet/BASE-ic.svg",
          "symbol": "$",
          "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        },
        "failure_reason": null,
        "from_address": "0x09b8c5b24bcdd91af5a7d32f6a4ae9fa4183d4f4",
        "inserted_at": "2025-08-14T15:24:59Z",
        "merchant_status": "CALLBACK_SUCCEEDED",
        "provider_transaction_id": "pay_31HdZ4DBbvrlttqdBixdsOcGJaq",
        "provider_wallet_reference": "d2c2a8bd-4473-4ee8-8d09-7f072162aae3",
        "status": "TXN_PROVIDER_SUCCEEDED",
        "to_address": "0x1817BCc039175F7e8bc629aB33c927381dAC8788",
        "transaction_data": {
          "amount": "1",
          "amount_usd": "0.989822010805417845",
          "chain_id": 8453,
          "created_at": "2025-08-14T15:23:03.043Z",
          "crypto_transaction": {
            "chain_id": 8453,
            "created_at": "2025-08-14T15:23:05.807Z",
            "payment_id": "pay_31HdZ4DBbvrlttqdBixdsOcGJaq",
            "status": "Success",
            "transaction_hash": "0x9c1583bacf1ec0a76ea9754e562abb008b80fa0ebd75f735e7f2674e866393ff",
            "type": "Withdraw",
            "updated_at": "2025-08-14T15:23:05.807Z"
          },
          "currency": "USDC",
          "event": "Payment.Updated"
        },
        "transaction_uuid": "3906fc3a-8983-49f4-979c-c8bbf3d8a02b",
        "trn_provider_ref": "BoomFi",
        "tx_hash": "0x9c1583bacf1ec0a76ea9754e562abb008b80fa0ebd75f735e7f2674e866393ff",
        "type": "Payout",
        "updated_at": "2025-08-14T15:24:59Z",
        "user_ref_id": "hub_player_2"
      }
    },
    {
      "cursor": "MjAyNS0wOC0xNFQxNToyMzowMlp8MmVmMjgyODEtYWY1Zi00MGNkLTg3YTMtMWViZDkzNjE1OGNk",
      "inserted_at": "2025-08-14T15:23:02Z",
      "node": {
        "amount": "1.000000000000000000000000000000",
        "amount_usd": null,
        "completed_at": null,
        "correlation_key": "d2c2a8bd-4473-4ee8-8d09-7f072162aae3",
        "currency": {
          "code": "USDC",
          "currency_icon": "https://cdn.hub88.io/hub-wallet/USDC-ic.svg",
          "id": "c872e749-fd56-533e-b01f-de87ae38e7f1",
          "name": "USD Coin",
          "network": "Base Chain",
          "network_icon": "https://cdn.hub88.io/hub-wallet/BASE-ic.svg",
          "symbol": "$",
          "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        },
        "failure_reason": null,
        "from_address": null,
        "inserted_at": "2025-08-14T15:23:02Z",
        "merchant_status": "CALLBACK_PENDING",
        "provider_transaction_id": null,
        "provider_wallet_reference": null,
        "status": "TXN_NEW",
        "to_address": "0x1817BCc039175F7e8bc629aB33c927381dAC8788",
        "transaction_data": {},
        "transaction_uuid": "2ef28281-af5f-40cd-87a3-1ebd936158cd",
        "trn_provider_ref": null,
        "tx_hash": null,
        "type": "Payout",
        "updated_at": "2025-08-14T15:23:02Z",
        "user_ref_id": "hub_player_2"
      }
    }
  ],
  "page_info": {
    "end_cursor": "dHJhbnNhY3Rpb246MjAyNS0wOC0xNFQxNToyMzowMnwyZWYyODI4MS1hZjVmLTQwY2QtODdhMy0xZWJkOTM2MTU4Y2Q=",
    "has_next_page": false,
    "has_previous_page": false,
    "start_cursor": "dHJhbnNhY3Rpb246MjAyNS0wOC0xNFQxNToyNDo1OXwzOTA2ZmMzYS04OTgzLTQ5ZjQtOTc5Yy1jOGJiZjNkOGEwMmI="
  },
  "total_count": 2
}