Skip to content

List Card Transactions ​

GET /openapi/v2/cards/transactions
ItemValue
HTTP methodGET
Request path/openapi/v2/cards/transactions
Request typequery

Request parameters:

FieldTypeRequiredDefaultDescription
cardIdstringYesNoneCard ID.
statusstringNoNoneFilter by platform transaction status: SUCCESS, FAILED, VOID, or PROCESSING; same as V1.
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[].amountstringOriginal purchase principal, excluding fees; a decimal string 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/nullConfirmed 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[].totalFeestring/nullSum 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[].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[].providerTransactionIdstring/nullService-provider transaction ID; null for recharge and withdrawal rows.
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; check chargeStatus to determine whether they were charged.
items[].fees[].currencystringFee currency.
items[].fees[].statusstringFee order status: CREATED, PROCESSING, UNKNOWN, FROZEN, SUCCESS, or FAILED.
items[].fees[].chargeStatusstring/nullActual 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[].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.

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:

  • amount is the original purchase principal, excluding all fees.
  • chargedAmount is 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 substitute amount + totalFee for the actual debit.
  • totalFee is the sum of additional fee order amounts, not the amount actually charged. Check each order's chargeStatus, not just its order status.
  • fees[].items are allocation details within a fee order, already included in fees[].amount. Fee order amounts are also included in totalFee; 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:

json
{
  "amount": "10.00",
  "chargedAmount": "11.25",
  "totalFee": "1.10",
  "currency": "USD",
  "fees": [
    {
      "feeOrderNo": "FEE001",
      "amount": "1.10",
      "currency": "USD",
      "status": "SUCCESS",
      "chargeStatus": "SUCCESS"
    }
  ]
}

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.