获取所有交易

概述

交易 API 允许您检索与您账户关联的所有财务交易的完整历史记录。这包括购买、存款、取款、转账、账单支付以及所有其他财务活动。 端点类型：GraphQL 查询
身份验证：必需（JWT Bearer 令牌）
所需权限范围：LIST_PAYMENT 和 LIST_PURCHASES
速率限制：适用标准的 GraphQL 速率限制

快速开始

基本查询

query GetTransactions {
  getTransactions {
    transactions {
      recordId
      transactionType
      amount
      status
      channel
      connectedAppId
      connectedAppName
      createdAt
    }
    totalCount
    hasNextPage
  }
}

查询结构

getTransactions(
  filter: TransactionFilterInput
  paginate: OffsetInput
): TransactionConnection!

参数

参数	类型	是否必需	描述
`filter`	`TransactionFilterInput`	否	交易的筛选条件
`paginate`	`OffsetInput`	否	分页参数（默认值为 limit=20, offset=0）

响应结构

TransactionConnection

type TransactionConnection {
  transactions: [Transaction]
  totalCount: Int!
  hasNextPage: Boolean!
}

字段	类型	描述
`transactions`	`[Transaction]`	交易记录数组
`totalCount`	`Int!`	符合筛选条件的交易总数（用于分页）
`hasNextPage`	`Boolean!`	是否还有更多结果

筛选选项

TransactionFilterInput

input TransactionFilterInput {
  # Record & Status
  recordId: [UUID]
  status: [TransactionStatus]
  
  # Amount Filters
  amount: Float
  amountGte: Float
  amountLte: Float
  finalAmount: Float
  finalAmountGte: Float
  finalAmountLte: Float
  
  # Cashback Filters
  cashbackAmount: Float
  cashbackAmountGte: Float
  cashbackAmountLte: Float
  cashbackPercentage: Float
  cashbackPercentageGte: Float
  cashbackPercentageLte: Float
  
  # Fee Filters
  feeAmount: Float
  feeAmountGte: Float
  feeAmountLte: Float
  
  # Date Filters
  createdGte: DateTime
  createdLte: DateTime
  updatedGte: DateTime
  updatedLte: DateTime
  
  # Merchant Filters
  merchantId: [UUID]
  merchant: [String]
  
  # Transaction Properties
  transactionType: [String]
  channel: [String!]
  category: [String]
  
  # Virtual Card Filters
  virtualCardProgram: [String]
  virtualCard: [UUID]
  
  # Other
  fundingSource: [String]
  userCashBalanceId: [UUID]
  referenceId: String
  liabilityId: UUID
}

筛选字段详情

记录与状态筛选

`recordId`

类型：[UUID]
描述：按特定的交易记录 ID 筛选。示例：

filter: {
  recordId: ["550e8400-e29b-41d4-a716-446655440000"]
}

`status`

类型：[TransactionStatus]
描述：按交易状态筛选。选项：

PENDING - 交易正在处理中
SETTLED - 交易已成功完成

示例：

filter: {
  status: [SETTLED]
}

金额筛选

`amount`、`amountGte`、`amountLte`

类型：Float
描述：按精确金额或以美元计的金额范围筛选。

amount - 精确匹配金额
amountGte - 最小金额（大于或等于）
amountLte - 最大金额（小于或等于）

示例：

# Transactions between $10 and $500
filter: {
  amountGte: 10.00
  amountLte: 500.00
}

`finalAmount`、`finalAmountGte`、`finalAmountLte`

类型：Float
描述：按最终金额（金额 + 手续费）筛选。示例：

filter: {
  finalAmountGte: 25.00
}

返现筛选

`cashbackAmount`、`cashbackAmountGte`、`cashbackAmountLte`

类型：Float
描述：按获得的返现金额筛选。示例：

# Transactions that earned $5 or more in cashback
filter: {
  cashbackAmountGte: 5.00
}

`cashbackPercentage`、`cashbackPercentageGte`、`cashbackPercentageLte`

类型：Float
描述：按返现比例筛选。示例：

# Transactions with 5% or higher cashback
filter: {
  cashbackPercentageGte: 5.0
}

手续费筛选

`feeAmount`、`feeAmountGte`、`feeAmountLte`

类型：Float
描述：按交易手续费金额筛选。示例：

# Transactions with fees
filter: {
  feeAmountGte: 0.01
}

日期筛选

`createdGte`、`createdLte`

类型：DateTime
格式：ISO 8601（例如：2025-01-01T00:00:00Z）
描述：按交易创建日期范围筛选。示例：

filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
}

`updatedGte`、`updatedLte`

类型：DateTime
描述：按交易最后更新日期范围筛选。

商户筛选

`merchantId`

类型：[UUID]
描述：按特定商户 ID 筛选。示例：

filter: {
  merchantId: ["550e8400-e29b-41d4-a716-446655440000"]
}

`merchant`

类型：[String]
描述：按商户名称筛选（与 destination 字段匹配）。示例：

filter: {
  merchant: ["Amazon", "Walmart"]
}

交易属性

`transactionType`

类型：[String]
描述：按特定交易类型筛选。 常见值：

Add Money - 存款
Gift Card Purchase - 礼品卡购买
Transfer - In - 转入
Transfer - Out - 转出
Virtual Card Purchase - 虚拟卡购买
Withdrawal

示例：

filter: {
  transactionType: ["Gift Card Purchase", "Add Money"]
}

`channel`

类型：[String!]
描述：按平台渠道筛选。 常见值：

WEB - 网页浏览器
MOBILE - 移动应用
API - API 请求

示例：

filter: {
  channel: ["WEB", "MOBILE"]
}

`category`

类型：[String]
描述：按交易类别筛选。示例：

filter: {
  category: ["Shopping", "Travel"]
}

虚拟卡筛选

`virtualCardProgram`

类型：[String]
描述：按虚拟卡项目/发卡行筛选。示例：

filter: {
  virtualCardProgram: ["TRANSPECOS", "SUTTON"]
}

`virtualCard`

类型：[UUID]
描述：按特定虚拟卡 ID 筛选。示例：

filter: {
  virtualCard: ["vc-1", "vc-2"]
}

其他筛选

`fundingSource`

类型：[String]
描述：搜索资金来源名称（与 source 或 destination 部分匹配）。示例：

filter: {
  fundingSource: ["Visa"]
}

`referenceId`

类型：String
描述：按外部参考 ID 筛选（例如购买展示 ID）。示例：

filter: {
  referenceId: "1000123"
}

`liabilityId`

类型：UUID
描述：按负债 ID 筛选（用于账单支付）。

分页

OffsetInput

input OffsetInput {
  limit: Int = 20
  offset: Int = 0
}

字段	类型	默认值	最大值	描述
`limit`	Int	20	20	每页返回的交易数量
`offset`	Int	0	-	要跳过的交易数量

示例 - 第 1 页：

paginate: {
  limit: 20
  offset: 0
}

示例 - 第 2 页：

paginate: {
  limit: 20
  offset: 20
}

示例 - 检查是否还有更多页：

query GetTransactions {
  getTransactions(paginate: { limit: 20, offset: 0 }) {
    transactions { recordId }
    hasNextPage  # Use this to determine if there are more results
    totalCount   # Total matching records
  }
}

Transaction 类型

type Transaction {
  recordId: UUID
  user: String!
  accountId: UUID!
  userId: UUID
  transactionType: String
  amount: Float!
  destination: String
  source: String
  externalFundingSourceActivity: Float
  fluzBalanceActivity: Float
  fee: Float
  cashback: Float
  
  # Ending balances after transaction
  giftCardPrepaymentBalanceAvailableBalance: Float
  giftCardPrepaymentBalanceTotalBalance: Float
  cashBalanceAvailableBalance: Float
  cashBalanceTotalBalance: Float
  seatBalanceAvailableBalance: Float
  seatBalanceTotalBalance: Float
  reserveBalanceAvailableBalance: Float
  reserveBalanceTotalBalance: Float
  otherCashBalanceAvailableBalance: Float
  otherCashBalanceTotalBalance: Float
  
  status: TransactionStatus
  referenceId: String
  description: String
  note: String
  category: String
  cardLastFour: String
  cardDisplayName: String
  originalCurrencyAmount: Float
  originalCurrencyCode: String
  conversionRate: Float
  merchantId: UUID
  descriptorId: UUID
  virtualCardProgram: String
  cashbackRate: Float
  bonusCashbackRate: Float
  channel: String
  sourceType: String
  logoUrl: String
  platformInstitutionLogo: String
  challengeLogoUrl: String
  invitedAccountId: UUID
  expectedClearedDate: DateTime
  liabilityId: UUID
  isGiftCardBalanceAffected: Boolean
  isCashBalanceAffected: Boolean
  isSeatBalanceAffected: Boolean
  isReserveBalanceAffected: Boolean
  transferId: UUID
  usedUserCashBalanceId: UUID
  connectedAppId: UUID
  connectedAppName: String
  
  memo: String
  transactionCategory: String
  attachmentUrl: String

  createdAt: DateTime
  updatedAt: DateTime
}

字段描述

核心交易字段

字段	类型	描述
`recordId`	UUID	此交易记录的唯一标识符
`user`	String	与交易关联的用户的显示名称
`accountId`	UUID	拥有此交易的账户
`userId`	UUID	发起交易的用户
`transactionType`	String	交易类型（PURCHASE、DEPOSIT 等）
`amount`	Float	以美元计的主要交易金额
`source`	String	资金的来源（例如 “Bank Card ****1234”）
`destination`	String	资金的去向（例如商户名称）
`status`	TransactionStatus	当前状态（PENDING 或 SETTLED）

财务详情

字段	类型	描述
`externalFundingSourceActivity`	Float	外部资金来源（银行卡/账户）的变动
`fluzBalanceActivity`	Float	Fluz 内部余额的变动
`fee`	Float	此交易收取的手续费
`cashback`	Float	此交易获得的返现
`cashbackRate`	Float	返现比例
`bonusCashbackRate`	Float	额外的奖励返现比例

余额快照

重要提示：所有余额字段显示的都是此交易生效之后的余额。

字段	描述
`cashBalanceAvailableBalance`	交易后的可用现金余额
`cashBalanceTotalBalance`	交易后的现金总余额
`seatBalanceAvailableBalance`	交易后的可用奖励余额
`seatBalanceTotalBalance`	交易后的奖励总余额
`giftCardPrepaymentBalanceAvailableBalance`	交易后的可用预付款余额
`giftCardPrepaymentBalanceTotalBalance`	交易后的预付款总余额
`reserveBalanceAvailableBalance`	交易后的可用储备金余额
`reserveBalanceTotalBalance`	交易后的储备金总余额
`otherCashBalanceAvailableBalance`	交易后的其他现金可用余额
`otherCashBalanceTotalBalance`	交易后的其他现金总余额

交易详情

字段	类型	描述
`referenceId`	String	外部参考（例如购买展示 ID）
`description`	String	人类可读的描述
`note`	String	附加备注
`category`	String	交易类别
`cardLastFour`	String	所用卡片的后 4 位数字（如适用）
`cardDisplayName`	String	支付方式的显示名称
`memo`	String	附加在此交易上的自由文本备注。通过 `updateTransactionMetadata` 设置，或在存款、购买和转账时设置。
`transactionCategory`	String	附加在此交易上的类别标签。通过 `updateTransactionMetadata` 设置，或在存款、购买和转账时设置。
`attachmentUrl`	String	此交易所附文件的签名 URL。通过 `updateTransactionMetadata` 设置，或在交易时设置。此 URL 会过期，请勿存储它。需要访问该文件时，请重新获取该交易。

商户信息

字段	类型	描述
`merchantId`	UUID	商户标识符
`descriptorId`	UUID	交易描述符 ID
`logoUrl`	String	商户/来源徽标的 URL

虚拟卡信息

字段	类型	描述
`virtualCardProgram`	String	虚拟卡项目（LITHIC、MARQETA 等）

货币转换

字段	类型	描述
`originalCurrencyAmount`	Float	发卡行报告的请求金额，以商户货币的最小单位表示（`6300` HKD 即 63.00 HKD）。在退款交易中，该金额是退款发生前仍被保留的金额，因此请以 `amount` 字段核对。
`originalCurrencyCode`	String	原始货币代码（例如 “EUR”）
`conversionRate`	Float	应用的汇率

元数据

字段	类型	描述
`channel`	String	平台渠道（WEB、MOBILE、API）
`sourceType`	String	资金来源类型
`liabilityId`	UUID	关联的负债（用于账单支付）
`transferId`	UUID	关联的转账（用于 P2P）
`usedUserCashBalanceId`	UUID	所使用的具体现金余额
`isGiftCardBalanceAffected`	Boolean	礼品卡余额是否发生变化
`isCashBalanceAffected`	Boolean	现金余额是否发生变化
`isSeatBalanceAffected`	Boolean	奖励余额是否发生变化
`isReserveBalanceAffected`	Boolean	储备金余额是否发生变化
`connectedAppId`	UUID	关联的应用程序 ID
`connectedAppName`	String	关联的应用程序名称
`createdAt`	DateTime	交易创建时间
`updatedAt`	DateTime	交易最后更新时间

示例

示例 1：基本交易列表

查询：

query GetRecentTransactions {
  getTransactions(
    paginate: { limit: 10, offset: 0 }
  ) {
    transactions {
      recordId
      transactionType
      amount
      description
      status
      cashback
      createdAt
    }
    totalCount
    hasNextPage
  }
}

响应：

{
  "data": {
    "getTransactions": {
      "transactions": [
        {
          "recordId": "550e8400-e29b-41d4-a716-446655440000",
          "transactionType": "GIFT_CARD_PURCHASE",
          "amount": 50.00,
          "description": "Gift card purchase at Amazon",
          "status": "SETTLED",
          "cashback": 2.50,
          "createdAt": "2025-01-15T14:30:00Z"
        },
        {
          "recordId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "transactionType": "DEPOSIT",
          "amount": 100.00,
          "description": "Cash Balance Deposit",
          "status": "SETTLED",
          "cashback": 0.00,
          "createdAt": "2025-01-14T10:15:00Z"
        }
      ],
      "totalCount": 2,
      "hasNextPage": false
    }
  }
}

示例 2：按日期范围筛选

查询：

query GetJanuaryTransactions {
  getTransactions(
    filter: {
      createdGte: "2025-01-01T00:00:00Z"
      createdLte: "2025-01-31T23:59:59Z"
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      recordId
      transactionType
      amount
      description
      status
      createdAt
    }
    totalCount
    hasNextPage
  }
}

示例 3：仅购买交易及余额

查询：

query GetPurchaseHistory {
  getTransactions(
    filter: {
      transactionType: ["GIFT_CARD_PURCHASE"]
      status: [SETTLED]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      recordId
      referenceId
      amount
      description
      source
      destination
      cashback
      cashbackRate
      cashBalanceAvailableBalance
      seatBalanceAvailableBalance
      createdAt
    }
    totalCount
    hasNextPage
  }
}

响应：

{
  "data": {
    "getTransactions": {
      "transactions": [
        {
          "recordId": "550e8400-e29b-41d4-a716-446655440000",
          "referenceId": "1000123",
          "amount": 50.00,
          "description": "Gift card purchase at Amazon",
          "source": "Visa ****1234",
          "destination": "Amazon",
          "cashback": 2.50,
          "cashbackRate": 5.0,
          "cashBalanceAvailableBalance": 102.50,
          "seatBalanceAvailableBalance": 25.00,
          "createdAt": "2025-01-15T14:30:00Z"
        }
      ],
      "totalCount": 1,
      "hasNextPage": false
    }
  }
}

示例 4：高返现交易

查询：

query GetHighCashbackTransactions {
  getTransactions(
    filter: {
      cashbackPercentageGte: 5.0
      status: [SETTLED]
    }
    paginate: { limit: 10, offset: 0 }
  ) {
    transactions {
      recordId
      transactionType
      amount
      description
      cashback
      cashbackRate
      status
      createdAt
    }
    totalCount
  }
}

示例 5：金额范围筛选

查询：

query GetMediumTransactions {
  getTransactions(
    filter: {
      amountGte: 50.00
      amountLte: 200.00
      status: [SETTLED]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      recordId
      amount
      transactionType
      description
      createdAt
    }
    totalCount
    hasNextPage
  }
}

示例 6：虚拟卡交易

查询：

query GetVirtualCardTransactions {
  getTransactions(
    filter: {
      virtualCardProgram: ["LITHIC", "MARQETA"]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      recordId
      amount
      description
      virtualCardProgram
      merchantId
      status
      createdAt
    }
    totalCount
  }
}

示例 7：分页示例

查询 - 获取第一页并检查是否还有更多：

query GetFirstPage {
  getTransactions(paginate: { limit: 20, offset: 0 }) {
    transactions {
      recordId
      amount
      transactionType
    }
    totalCount
    hasNextPage
  }
}

响应显示 hasNextPage=true：

{
  "data": {
    "getTransactions": {
      "transactions": [...],
      "totalCount": 150,
      "hasNextPage": true
    }
  }
}

查询 - 获取第二页：

query GetSecondPage {
  getTransactions(paginate: { limit: 20, offset: 20 }) {
    transactions {
      recordId
      amount
      transactionType
    }
    totalCount
    hasNextPage
  }
}

错误处理

常见错误

缺失或无效的令牌

{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

HTTP 状态：401 Unauthorized

权限不足

{
  "errors": [
    {
      "message": "Insufficient permissions: LIST_PAYMENT and LIST_PURCHASES scopes required",
      "extensions": {
        "code": "FORBIDDEN",
        "requiredScopes": ["LIST_PAYMENT", "LIST_PURCHASES"]
      }
    }
  ]
}

HTTP 状态：403 Forbidden

无效的筛选参数

{
  "errors": [
    {
      "message": "Invalid date format for createdGte",
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

HTTP 状态：400 Bad Request

超出速率限制

{
  "message": "Rate limit exceeded"
}

HTTP 状态：429 Too Many Requests 这是一个普通的 JSON 响应体，而不是 GraphQL 的 errors 数组。有关阻断持续时间，请参阅速率限制。

最佳实践

1. 有效使用分页

始终检查 hasNextPage 以确定是否还有更多结果：

async function fetchAllTransactions() {
  const allTransactions = [];
  let offset = 0;
  const limit = 20;
  
  while (true) {
    const result = await getTransactions({ 
      paginate: { limit, offset } 
    });
    
    allTransactions.push(...result.transactions);
    
    if (!result.hasNextPage) break;
    offset += limit;
  }
  
  return allTransactions;
}

2. 仅请求所需字段

仅指定您需要的字段以减小响应大小：

# Good - minimal fields
getTransactions {
  transactions {
    recordId
    amount
    transactionType
    createdAt
  }
  totalCount
  hasNextPage
}

# Less efficient - requesting all 40+ fields
getTransactions {
  transactions {
    recordId
    transactionType
    amount
    ... (all fields)
  }
}

3. 对历史查询使用日期筛选

查询较早的交易时，请始终使用日期筛选：

# Good
filter: {
  createdGte: "2024-01-01T00:00:00Z"
  createdLte: "2024-12-31T23:59:59Z"
}

4. 缓存已结算的交易

状态为 status: SETTLED 的交易是不可变的，可以被缓存：

// Example caching strategy
const cacheKey = `transactions:${accountId}:${createdGte}:${createdLte}`;
let result = cache.get(cacheKey);

if (!result) {
  result = await getTransactions({
    filter: { status: ['SETTLED'], createdGte, createdLte }
  });
  cache.set(cacheKey, result, '1 hour');
}

5. 高效组合筛选条件

使用范围筛选先缩小结果范围，再应用其他筛选条件：

# Efficient - date range first
filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
  transactionType: ["GIFT_CARD_PURCHASE"]
  amountGte: 50.00
}

速率限制

此查询与 GraphQL API 共享相同的限制。有关具体数值以及被拒绝请求的表现形式，请参阅速率限制。

代码示例

JavaScript/TypeScript

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://transactional-graph.fluzapp.com/api/v1/graphql',
  cache: new InMemoryCache(),
  headers: {
    authorization: `Bearer ${accessToken}`,
  },
});

const GET_TRANSACTIONS = gql`
  query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) {
    getTransactions(filter: $filter, paginate: $paginate) {
      transactions {
        recordId
        transactionType
        amount
        description
        status
        cashback
        createdAt
      }
      totalCount
      hasNextPage
    }
  }
`;

async function fetchTransactions() {
  const { data } = await client.query({
    query: GET_TRANSACTIONS,
    variables: {
      filter: {
        status: ['SETTLED'],
        createdGte: '2025-01-01T00:00:00Z',
      },
      paginate: {
        limit: 20,
        offset: 0,
      },
    },
  });
  
  return data.getTransactions;
}

Python

import requests

def get_transactions(access_token, created_gte=None, created_lte=None, limit=20, offset=0):
    url = "https://transactional-graph.fluzapp.com/api/v1/graphql"
    
    query = """
        query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) {
            getTransactions(filter: $filter, paginate: $paginate) {
                transactions {
                    recordId
                    transactionType
                    amount
                    description
                    status
                    cashback
                    createdAt
                }
                totalCount
                hasNextPage
            }
        }
    """
    
    variables = {
        "filter": {},
        "paginate": {
            "limit": limit,
            "offset": offset
        }
    }
    
    if created_gte:
        variables["filter"]["createdGte"] = created_gte
    if created_lte:
        variables["filter"]["createdLte"] = created_lte
    
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    response = requests.post(
        url,
        json={"query": query, "variables": variables},
        headers=headers
    )
    
    return response.json()["data"]["getTransactions"]

# Usage
result = get_transactions(
    access_token="your_token_here",
    created_gte="2025-01-01T00:00:00Z",
    limit=20
)

print(f"Found {result['totalCount']} transactions")
print(f"Has more pages: {result['hasNextPage']}")

cURL

curl -X POST https://transactional-graph.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) { getTransactions(filter: $filter, paginate: $paginate) { transactions { recordId transactionType amount description status cashback createdAt } totalCount hasNextPage } }",
    "variables": {
      "filter": {
        "status": ["SETTLED"],
        "createdGte": "2025-01-01T00:00:00Z"
      },
      "paginate": {
        "limit": 20,
        "offset": 0
      }
    }
  }'

常见问题

问：单次请求最多可以获取多少笔交易？

答：单次请求的最大限制是 20 笔交易。请使用 hasNextPage 字段实现分页。

问：交易历史可以追溯到多久以前？

答：自账户创建以来的所有交易都会被永久保留。

问：是否包含处理中的交易？

答：是的，默认情况下会包含处理中的交易。可以通过按 status: [SETTLED] 筛选来排除它们。

问：时间戳使用的是什么时区？

答：所有时间戳均为 UTC 时间（ISO 8601 格式）。

问：我需要哪些权限范围？

答：您同时需要 LIST_PAYMENT 和 LIST_PURCHASES 权限范围。

问：我可以在账户内按用户 ID 筛选吗？

答：不可以，该 API 始终返回您账户下的所有交易，不支持用户级别的筛选。

问：`amount` 筛选和 `finalAmount` 筛选有什么区别？

答：

amount 筛选的是基础交易金额
finalAmount 筛选的是金额 + 手续费（即向用户收取的总额）

问：如何按日期范围筛选？

答：使用 createdGte 和 createdLte 筛选创建日期：

filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
}

支持

API 状态：https://status.fluz.app
开发者门户：https://developers.fluz.app
支持邮箱：api-support@fluz.app
Slack 社区：https://fluz-dev.slack.com

更新日志

v1.0.0（分支：13-fluz-15659-add-transactions-query-and-webhook-to-api）

交易查询 API 的首个正式版本
支持全面的筛选功能（15+ 种筛选类型）
使用 TransactionConnection 响应类型进行分页
交易记录中包含余额快照
需要 LIST_PAYMENT 和 LIST_PURCHASES 权限范围
仅支持账户级别的交易访问

需要帮助？ 请通过 api-support@fluz.app 联系我们的开发者支持团队，或访问我们的开发者门户。

​概述

​快速开始

​基本查询

​查询结构

​参数

​响应结构

​TransactionConnection

​筛选选项

​TransactionFilterInput

​筛选字段详情

​记录与状态筛选

recordId

status

​金额筛选

amount、amountGte、amountLte

finalAmount、finalAmountGte、finalAmountLte

​返现筛选

cashbackAmount、cashbackAmountGte、cashbackAmountLte

cashbackPercentage、cashbackPercentageGte、cashbackPercentageLte

​手续费筛选

feeAmount、feeAmountGte、feeAmountLte

​日期筛选

createdGte、createdLte

updatedGte、updatedLte

​商户筛选

merchantId

merchant

​交易属性

transactionType

channel

category

​虚拟卡筛选

virtualCardProgram

virtualCard

​其他筛选

fundingSource

referenceId

liabilityId

​分页

​OffsetInput

​Transaction 类型

​字段描述

​核心交易字段

​财务详情

​余额快照

​交易详情

​商户信息

​虚拟卡信息

​货币转换

​元数据

​示例

​示例 1：基本交易列表

​示例 2：按日期范围筛选

​示例 3：仅购买交易及余额

​示例 4：高返现交易

​示例 5：金额范围筛选

​示例 6：虚拟卡交易

​示例 7：分页示例

​错误处理

​常见错误

​缺失或无效的令牌

​权限不足

​无效的筛选参数

​超出速率限制

​最佳实践

​1. 有效使用分页

​2. 仅请求所需字段

​3. 对历史查询使用日期筛选

​4. 缓存已结算的交易

​5. 高效组合筛选条件

​速率限制

​代码示例

​JavaScript/TypeScript

​Python

​cURL

​常见问题

​问：单次请求最多可以获取多少笔交易？

​问：交易历史可以追溯到多久以前？

​问：是否包含处理中的交易？

​问：时间戳使用的是什么时区？

概述