List Card Transactions
GET/openapi/v1/cards/transactionsAvailable only for card products supported by V1. Use the V2 endpoint for other card products.
| Item | Value |
|---|---|
| HTTP method | GET |
| Request path | /openapi/v1/cards/transactions |
| Request type | query |
Request parameters:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
cardId | string | Yes | None | Card ID. |
status | string | No | None | Filter by platform transaction status: SUCCESS, FAILED, VOID, or PROCESSING; same as V2. |
currency | string | No | None | Transaction currency, usually a three-letter ISO 4217 code; values are not restricted to a fixed set. |
fromTime | string | No | None | Start time, as an ISO 8601 date-time string. |
toTime | string | No | None | End time, as an ISO 8601 date-time string. |
page | integer | No | 1 | Page number, starting at 1. |
pageSize | integer | No | 20 | Number of items per page, from 1 to 100. |
Response data
| Field | Type | Description |
|---|---|---|
items | array | List of transactions. |
items[].id | string | Transaction ID. |
items[].cardId | string | Card ID. |
items[].memberId | string | Platform member ID. |
items[].amount | string / null | Original purchase principal excluding all fees, in currency. |
items[].accountPrincipalAmount | string/null | Account-currency consumption principal, excluding channel fees; null when unavailable. Do not infer it from the original transaction amount. |
items[].accountCurrency | string/null | Currency paired with accountPrincipalAmount; may differ from currency. |
items[].chargedAmount | string / null | Cumulative confirmed debit to date, including the provider debit and confirmed additional charges. Pending fees do not hide known debits; null when base debit or confirmed charge facts are incomplete. |
items[].totalFee | string / null | Total platform and tenant additional fee order amounts, excluding provider fees; does not imply successful charging. Zero when no additional fee orders exist, null when order amounts are missing or currencies cannot be reconciled. |
items[].currency | string | Transaction currency, usually a three-letter ISO 4217 code; additional values may be introduced. |
items[].status | string | Platform transaction status: SUCCESS, FAILED, VOID, or PROCESSING. |
items[].providerStatus | string/null | Raw provider transaction status for troubleshooting; values may be extended. |
items[].occurredAt | string | Transaction occurrence time, as an ISO 8601 date-time string. |
items[].providerTransactionId | string | Provider transaction ID. |
items[].transactionType | string | Platform transaction type: CONSUMPTION, REFUND, VOID, RECHARGE, or WITHDRAWAL. |
items[].providerTransactionType | string/null | Raw provider transaction type for troubleshooting; values may be extended. |
items[].originalTransactionId | string/null | Original transaction ID for a refund, void, or another derived transaction. |
items[].countryCode | string | Purchase country or region code, when supplied by the upstream provider. |
items[].merchantName | string | Merchant display name, when supplied by the card network or upstream processor. |
items[].merchantCategoryCode | string | Four-digit merchant category code (MCC), when supplied by the upstream provider. |
items[].fees | array | Platform and tenant additional fee orders; excludes the provider’s own fees. |
items[].fees[].feeOrderNo | string | Fee order number. |
items[].fees[].amount | string | Combined platform and tenant fees for this order; chargeStatus indicates whether they were charged. |
items[].fees[].currency | string | Fee currency. |
items[].fees[].status | string | Fee order status: CREATED, PROCESSING, UNKNOWN, FROZEN, SUCCESS, or FAILED. |
items[].fees[].chargeStatus | string / null | Additional fee charge status: SUCCESS means charged; FAILED / NOT_STARTED means not charged; UNKNOWN / PROCESSING or null means unconfirmed. Independent of order and allocation status. |
items[].fees[].providerTransferId | string | Provider transfer ID. |
items[].fees[].providerStatus | string | Provider transfer status. |
items[].fees[].completedTime | string | Fee order completion time. |
items[].fees[].items | array | Fee allocation items for this order, already included in the order’s amount; do not add them again. |
items[].fees[].items[].feeCode | string | Fee code. |
items[].fees[].items[].beneficiaryTenantId | string | Beneficiary tenant ID. |
items[].fees[].items[].amount | string | Line item amount. |
items[].fees[].items[].currency | string | Line item currency. |
page | integer | Current page number. |
pageSize | integer | Number of items per page. |
total | integer | Total count. |
Amounts and fees
All amounts are decimal strings. Do not sum them using floating-point arithmetic. Consumption webhooks and this query use the same amount definitions:
amountis the purchase principal excluding fees.chargedAmountis the cumulative confirmed debit to date, including the provider debit and confirmed platform and tenant charges. Do not addfeesortotalFeeagain.totalFeeis the sum of platform and tenant additional fee order amounts. It excludes provider fees and does not imply successful charging. Do not useamount + totalFeein place ofchargedAmount.feescontains additional fee orders;fees[].itemscontains their allocations. These are totals and their breakdowns, not separate charges.- Fee order
statusdescribes order processing;chargeStatusdescribes the debit result. Successfully charged fees count towardchargedAmounteven while local allocation is still processing. - Known provider debits and successfully charged fees remain included in
chargedAmountwhile the transaction or other fees are pending, or before fee orders exist. Unstarted, pending, unknown, and failed charges are excluded until confirmed successful.chargedAmountis null if provider debit data or the fee list is unavailable, or confirmed charge facts are invalid (including incompatible currencies, missing amounts, or missing or duplicate order numbers). Do not substitute principal or estimated fees. Known principal remains available asamount, and known additional fee order amounts remain included intotalFee. - With
fees: [],totalFeeis zero, but provider fees may still apply. Hong Kong purchases follow the additional-fee exemption rule, whilechargedAmountstill includes provider fees. Purchases elsewhere also return the known provider debit before additional fee orders exist; this does not imply a final fee exemption. - USD and USDT are combined at 1:1 for card purchases. Other currencies are not added directly.
- A webhook is a snapshot when the event is created; this query returns the latest state. Subsequent charge confirmation may update
chargedAmount.
For example, a purchase principal of USD 10, a provider debit of USD 10.15, a platform fee of USD 0.05, and a tenant fee of USD 1.05, with the additional fees successfully charged:
json
{
"amount": "10.00",
"chargedAmount": "11.25",
"totalFee": "1.10",
"currency": "USD",
"fees": [
{
"feeOrderNo": "FEE001",
"amount": "1.10",
"currency": "USD",
"status": "SUCCESS",
"chargeStatus": "SUCCESS"
}
]
}