交易列表

返回當前 AppID 賬號下 所有虛擬卡 的 交易明細（消費、退款、撤銷、手續費等），支援分頁和豐富的篩選條件。

• 範圍始終限於你自己的賬號 —— 服務端會根據你的 HMAC 憑證繫結賬號，無法查詢其他賬號的資料。
• 嚴格 脫敏：不含完整 PAN、不含持卡人 PII、不含提供商側 / 內部訂單引用。每條記錄都攜帶 card_id + last_four，便於你歸因到具體卡片。
• 如需查詢 單張 卡，請使用 卡片交易列表（或在此處以可選篩選項傳入 card_id）。

端點

項	值
Method	POST
Path	/api/v1/openapi/transactions/list
鑑權	HMAC
冪等鍵	不需要

請求欄位

所有欄位均為可選。

欄位	型別	預設值	說明
card_id	string	—	可選篩選項 —— card_<id>。傳入後結果僅限該卡（會校驗歸屬 + 虛擬卡型別）。
transaction_time_from	string	—	交易時間範圍起點，格式 YYYY-MM-DD HH:MM:SS
transaction_time_to	string	—	交易時間範圍終點，格式 YYYY-MM-DD HH:MM:SS
type	string	—	型別篩選 —— 見 型別取值
status	string	—	狀態篩選 —— 取 PENDING / APPROVED / FAILED / REVERSED 之一
amount_from	string	—	交易金額下限，如 "10.00"
amount_to	string	—	交易金額上限，如 "1000.00"
merchant_name	string	—	商戶名稱（模糊匹配）
keyword	string	—	自由文本關鍵詞（在商戶 / 描述 / 城市 等上模糊匹配）
page	int	1	頁碼（≥ 1）
page_size	int	20	每頁數量（≤ 100）

請求示例

{
  "status": "APPROVED",
  "transaction_time_from": "2026-04-01 00:00:00",
  "transaction_time_to": "2026-04-30 23:59:59",
  "page": 1,
  "page_size": 20
}

響應

一個分頁信封（list / total / page / page_size / total_pages / has_next / has_prev）。list 中的每一項都是一筆交易：

交易欄位

欄位	型別	說明
transaction_id	string	txn_<id> —— 不透明令牌，請勿解析
card_id	string	該交易所屬的 card_<id>
card_type	string	小寫業務程式碼（virtual_v …）
card_brand	string	卡組織展示名（如 VISA）
last_four	string	卡號末 4 位（絕不含完整 PAN）
type	string	歸一化後的大寫型別（PURCHASE / REFUND / AUTHORIZATION / REVERSAL / FEE …）
type_category	string	用於標籤配色的歸一化分類 —— 見 分類
type_i18n	object	{ "en-US": …, "zh-CN": …, "zh-HK": … } 展示文案
status	string	PENDING / APPROVED / FAILED / REVERSED
transaction_time	string nullable	交易發生時間（提供商時鐘）。未知時為 null
transaction_currency	string	交易幣種（ISO 4217）
transaction_amount	string	交易金額（小數字符串，2 位小數）
billing_currency	string	賬單 / 卡內幣種
billing_amount	string	賬單金額（小數字符串，2 位小數）
merchant_name	string	商戶名稱
merchant_id	string	商戶 ID（由卡組織上報）
merchant_category	string	商戶分類 / MCC 標籤
merchant_country	string	商戶國家（如 US）
merchant_city	string	商戶城市
merchant_logo_url	string	品牌 Logo URL（解析完成前可能為空）
approval_code	string	批准碼（對賬用）
auth_code	string	授權碼（對賬用）
cross_border_type	string	0 = 境內，1 = 跨境
decline_reason	string	失敗 / 拒付原因（如適用）
description	string	交易描述
remark	string	備註
created_at	string	記錄入庫時間

省略欄位是刻意的

為空的可選字串欄位會從 JSON 中整體省略（而非 null）。文件所述結構即完整契約 —— 內部 DB ID、提供商交易 ID、關聯訂單號、使用者身份以及完整 PAN 絕不返回。參見 ID 與字首。

響應示例

{
  "code": 200,
  "message": "OK",
  "data": {
    "list": [
      {
        "transaction_id": "txn_9087654",
        "card_id": "card_12345",
        "card_type": "virtual_v",
        "card_brand": "VISA",
        "last_four": "1234",
        "type": "PURCHASE",
        "type_category": "consumption",
        "type_i18n": { "en-US": "Purchase", "zh-CN": "消費", "zh-HK": "消費" },
        "status": "APPROVED",
        "transaction_time": "2026-04-12T08:31:20Z",
        "transaction_currency": "USD",
        "transaction_amount": "12.90",
        "billing_currency": "USD",
        "billing_amount": "12.90",
        "merchant_name": "OPENAI",
        "merchant_country": "US",
        "merchant_logo_url": "https://img.logo.dev/openai.com",
        "approval_code": "091234",
        "cross_border_type": "0",
        "created_at": "2026-04-12T08:31:25Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

型別取值

type 請求篩選項接受以下標準列舉（服務端會對映到各提供商的原始值）：

值	含義
PURCHASE	消費 / 已結算購買
AUTHORIZATION	預授權（佔用，未結算）
REFUND	退款
REVERSAL	撤銷
TOPUP	充值 / 充值入賬
WITHDRAW	提現
FEE	手續費

未知值會做精確匹配（通常返回空結果）。響應中的 type 欄位是歸一化後的大寫原始型別；請在你的一側對映用於展示，或使用 type_i18n。

型別分類

type_category 取以下之一：consumption · refund · reversal · topup · fee · close · transfer · withdraw · interest · 3ds · unknown。

隱藏的交易型別

內部記賬型別（如系統追加的跨境手續費行、銷卡記賬條目）會從本介面隱藏，與面向客戶的 App 一致。卡片銷卡時間之後的交易同樣被排除。

常見錯誤

HTTP	message_key	說明
400	openapi_invalid_card_id	card_id 篩選項錯誤
400	openapi_card_type_not_supported	card_id 篩選項指向非虛擬卡
400	invalid_date_format	transaction_time_from/to 不符合 YYYY-MM-DD HH:MM:SS
400	invalid_params	金額格式錯誤（amount_from / amount_to）
401	openapi_invalid_credentials	鑑權失敗
404	card_not_found	card_id 篩選項不存在 / 不屬於當前賬號
500	openapi_list_transactions_failed	服務端異常

說明

• 資料來自 Coinepay 的本地賬本（由提供商 webhook 填充）；本介面不會同步呼叫上游提供商。
• 即時流水優先使用 webhook（card.*）；本介面用於定期對賬與歷史查詢。