List Transactions

Returns transaction details (purchases, refunds, reversals, fees, etc.) across all virtual cards under the current AppID account, with pagination and rich filters.

• Scope is always your own account — the server binds the account from your HMAC credential; there is no way to query another account's data.
• Strictly desensitized: no full PAN, no cardholder PII, no provider-side / internal order references. Each row carries card_id + last_four so you can attribute it to a card.
• To query a single card, use List Card Transactions (or pass card_id here as an optional filter).

Endpoint

Item	Value
Method	POST
Path	/api/v1/openapi/transactions/list
Auth	HMAC
Idempotency	Not required

Request Fields

All fields are optional.

Field	Type	Default	Description
card_id	string	—	Optional filter — card_<id>. When provided, results are limited to that card (ownership + virtual-type validated).
transaction_time_from	string	—	Start of transaction-time range, format YYYY-MM-DD HH:MM:SS
transaction_time_to	string	—	End of transaction-time range, format YYYY-MM-DD HH:MM:SS
type	string	—	Type filter — see Type values
status	string	—	Status filter — one of PENDING / APPROVED / FAILED / REVERSED
amount_from	string	—	Minimum transaction amount, e.g. "10.00"
amount_to	string	—	Maximum transaction amount, e.g. "1000.00"
merchant_name	string	—	Merchant name (fuzzy match)
keyword	string	—	Free-text keyword (fuzzy match over merchant / description / city / etc.)
page	int	1	Page number (≥ 1)
page_size	int	20	Page size (≤ 100)

Example Request

{
  "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
}

Response

A paginated envelope (list / total / page / page_size / total_pages / has_next / has_prev). Each item in list is a transaction:

Transaction Fields

Field	Type	Description
transaction_id	string	txn_<id> — opaque token, do not parse
card_id	string	card_<id> the transaction belongs to
card_type	string	Lowercase business code (virtual_v …)
card_brand	string	Brand display name (e.g. VISA)
last_four	string	Last 4 digits of the card (never the full PAN)
type	string	Normalized upper-case type (PURCHASE / REFUND / AUTHORIZATION / REVERSAL / FEE …)
type_category	string	Normalized category for tag coloring — see Categories
type_i18n	object	{ "en-US": …, "zh-CN": …, "zh-HK": … } display labels
status	string	PENDING / APPROVED / FAILED / REVERSED
transaction_time	string nullable	When the transaction occurred (provider clock). null if unknown
transaction_currency	string	Transaction currency (ISO 4217)
transaction_amount	string	Transaction amount (decimal string, 2 dp)
billing_currency	string	Billing / card currency
billing_amount	string	Billing amount (decimal string, 2 dp)
merchant_name	string	Merchant name
merchant_id	string	Merchant ID (as reported by the network)
merchant_category	string	Merchant category / MCC label
merchant_country	string	Merchant country (e.g. US)
merchant_city	string	Merchant city
merchant_logo_url	string	Brand logo URL (may be empty until resolved)
approval_code	string	Approval code (reconciliation)
auth_code	string	Authorization code (reconciliation)
cross_border_type	string	0 = domestic, 1 = cross-border
decline_reason	string	Failure / decline reason, when applicable
description	string	Transaction description
remark	string	Remark
created_at	string	When the record was stored

Omitted fields are intentional

Empty optional string fields are omitted from the JSON entirely (not null). The documented shape is the complete contract — internal DB IDs, provider transaction IDs, related order numbers, user identity and full PAN are never returned. See IDs & Prefixes.

Example Response

{
  "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 values

The type request filter accepts these standard enums (mapped server-side to each provider's raw values):

Value	Meaning
PURCHASE	Consumption / settled purchase
AUTHORIZATION	Pre-authorization (held, not settled)
REFUND	Refund
REVERSAL	Reversal
TOPUP	Top-up / recharge posting
WITHDRAW	Withdrawal
FEE	Fee

Unknown values are matched exactly (and will typically return no rows). The response type field is the normalized upper-case raw type; map it on your side for display, or use type_i18n.

Type categories

type_category is one of: consumption · refund · reversal · topup · fee · close · transfer · withdraw · interest · 3ds · unknown.

Hidden transaction types

Internal bookkeeping types (e.g. system-added cross-border fee lines and card-close entries) are hidden from this endpoint, matching the customer-facing app. Transactions after a card's close time are also excluded.

Common Errors

HTTP	message_key	Description
400	openapi_invalid_card_id	Bad card_id filter
400	openapi_card_type_not_supported	card_id filter points to a non-virtual card
400	invalid_date_format	transaction_time_from/to not in YYYY-MM-DD HH:MM:SS
400	invalid_params	Bad amount format (amount_from / amount_to)
401	openapi_invalid_credentials	Auth failure
404	card_not_found	card_id filter not found / not owned
500	openapi_list_transactions_failed	Server error

Notes

• Data is served from Coinepay's local ledger (populated from provider webhooks); this endpoint does not call the upstream provider synchronously.
• Prefer webhooks (card.*) for real-time flow; use this endpoint for periodic reconciliation and history.