List Card Transactions
GET/openapi/v2/cards/transactions| Item | Value |
|---|---|
| HTTP method | GET |
| Request path | /openapi/v2/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 V1. |
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 | Original purchase principal, excluding fees; a decimal string 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 | Confirmed cumulative debit so far, including the provider debit and successfully charged additional fees. Pending fees do not hide known debits; null when base debit or confirmed charge facts are incomplete or inconsistent. |
items[].totalFee | string/null | Sum of platform and tenant additional fee order amounts, excluding the provider's own fees; does not imply successful charging. 0 when there are no fee orders, or null when 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/null | Service-provider transaction ID; null for recharge and withdrawal rows. |
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; check chargeStatus to determine 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 | Actual fee charge status, independent of the order status: SUCCESS means charged; FAILED or NOT_STARTED means not charged; UNKNOWN, PROCESSING, or null means unconfirmed. |
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. |
Amount and fee definitions
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 original purchase principal, excluding all fees.chargedAmountis the confirmed provider debit plus successfully charged additional fees. Fees that have not started, are processing, have an unknown outcome, or failed are excluded until successfully charged. Do not substituteamount + totalFeefor the actual debit.totalFeeis the sum of additional fee order amounts, not the amount actually charged. Check each order'schargeStatus, not just its orderstatus.fees[].itemsare allocation details within a fee order, already included infees[].amount. Fee order amounts are also included intotalFee; do not add them again.
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, produce totalFee of USD 1.10 and chargedAmount of USD 11.25. The following shows only the amount and fee fields of one purchase record, not a complete paginated response:
{
"amount": "10.00",
"chargedAmount": "11.25",
"totalFee": "1.10",
"currency": "USD",
"fees": [
{
"feeOrderNo": "FEE001",
"amount": "1.10",
"currency": "USD",
"status": "SUCCESS",
"chargeStatus": "SUCCESS"
}
]
}Local records and related refunds
This endpoint reads local transactions for the current tenant. Refunds explicitly linked to an original purchase on the same card and with the same service provider are included in that purchase's processing history, rather than listed separately. Unlinked refunds remain separate rows; amounts or timestamps alone do not establish a relationship. The purchase amount remains its original principal and is not reduced by refunds.
Pass items[].id and items[].transactionType to the processing-history endpoint. For purchases, refunds, and voids, id is the service-provider transaction ID. For recharges and withdrawals, id is the platform order number and providerTransactionId is null.
