Skip to content

List Card Transactions ​

GET /openapi/v1/cards/transactions

Available only for card products supported by V1. Use the V2 endpoint for other card products.

ItemValue
HTTP methodGET
Request path/openapi/v1/cards/transactions
Request typequery

Request parameters:

FieldTypeRequiredDefaultDescription
cardIdstringYesNoneCard ID.
statusstringNoNoneFilter by platform transaction status: SUCCESS, FAILED, VOID, or PROCESSING; same as V2.
currencystringNoNoneTransaction currency, usually a three-letter ISO 4217 code; values are not restricted to a fixed set.
fromTimestringNoNoneStart time, as an ISO 8601 date-time string.
toTimestringNoNoneEnd time, as an ISO 8601 date-time string.
pageintegerNo1Page number, starting at 1.
pageSizeintegerNo20Number of items per page, from 1 to 100.

Response data ​

FieldTypeDescription
itemsarrayList of transactions.
items[].idstringTransaction ID.
items[].cardIdstringCard ID.
items[].memberIdstringPlatform member ID.
items[].amountstring / nullOriginal purchase principal excluding all fees, in currency.
items[].accountPrincipalAmountstring/nullAccount-currency consumption principal, excluding channel fees; null when unavailable. Do not infer it from the original transaction amount.
items[].accountCurrencystring/nullCurrency paired with accountPrincipalAmount; may differ from currency.
items[].chargedAmountstring / nullCumulative 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[].totalFeestring / nullTotal 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[].currencystringTransaction currency, usually a three-letter ISO 4217 code; additional values may be introduced.
items[].statusstringPlatform transaction status: SUCCESS, FAILED, VOID, or PROCESSING.
items[].providerStatusstring/nullRaw provider transaction status for troubleshooting; values may be extended.
items[].occurredAtstringTransaction occurrence time, as an ISO 8601 date-time string.
items[].providerTransactionIdstringProvider transaction ID.
items[].transactionTypestringPlatform transaction type: CONSUMPTION, REFUND, VOID, RECHARGE, or WITHDRAWAL.
items[].providerTransactionTypestring/nullRaw provider transaction type for troubleshooting; values may be extended.
items[].originalTransactionIdstring/nullOriginal transaction ID for a refund, void, or another derived transaction.
items[].countryCodestringPurchase country or region code, when supplied by the upstream provider.
items[].merchantNamestringMerchant display name, when supplied by the card network or upstream processor.
items[].merchantCategoryCodestringFour-digit merchant category code (MCC), when supplied by the upstream provider.
items[].feesarrayPlatform and tenant additional fee orders; excludes the provider’s own fees.
items[].fees[].feeOrderNostringFee order number.
items[].fees[].amountstringCombined platform and tenant fees for this order; chargeStatus indicates whether they were charged.
items[].fees[].currencystringFee currency.
items[].fees[].statusstringFee order status: CREATED, PROCESSING, UNKNOWN, FROZEN, SUCCESS, or FAILED.
items[].fees[].chargeStatusstring / nullAdditional 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[].providerTransferIdstringProvider transfer ID.
items[].fees[].providerStatusstringProvider transfer status.
items[].fees[].completedTimestringFee order completion time.
items[].fees[].itemsarrayFee allocation items for this order, already included in the order’s amount; do not add them again.
items[].fees[].items[].feeCodestringFee code.
items[].fees[].items[].beneficiaryTenantIdstringBeneficiary tenant ID.
items[].fees[].items[].amountstringLine item amount.
items[].fees[].items[].currencystringLine item currency.
pageintegerCurrent page number.
pageSizeintegerNumber of items per page.
totalintegerTotal 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:

  • amount is the purchase principal excluding fees.
  • chargedAmount is the cumulative confirmed debit to date, including the provider debit and confirmed platform and tenant charges. Do not add fees or totalFee again.
  • totalFee is the sum of platform and tenant additional fee order amounts. It excludes provider fees and does not imply successful charging. Do not use amount + totalFee in place of chargedAmount.
  • fees contains additional fee orders; fees[].items contains their allocations. These are totals and their breakdowns, not separate charges.
  • Fee order status describes order processing; chargeStatus describes the debit result. Successfully charged fees count toward chargedAmount even while local allocation is still processing.
  • Known provider debits and successfully charged fees remain included in chargedAmount while the transaction or other fees are pending, or before fee orders exist. Unstarted, pending, unknown, and failed charges are excluded until confirmed successful. chargedAmount is 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 as amount, and known additional fee order amounts remain included in totalFee.
  • With fees: [], totalFee is zero, but provider fees may still apply. Hong Kong purchases follow the additional-fee exemption rule, while chargedAmount still 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"
    }
  ]
}