List Card Transactions

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.valox.co/api/v1/cards/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "createdAt": "2024-01-15T14:30:00Z",
    "clearedAt": null,
    "isPending": true,
    "kind": "Payment",
    "status": "Approved",
    "country": {
      "name": "United Kingdom",
      "numeric": "826",
      "alpha2": "GB",
      "alpha3": "GBR"
    },
    "mcc": "5411",
    "merchant": {
      "name": "TESCO STORES",
      "city": "LONDON",
      "country": {
        "name": "United Kingdom",
        "alpha2": "GB"
      }
    },
    "billingAmount": "2550",
    "billingCurrency": {
      "symbol": "€",
      "code": "EUR",
      "decimals": 2,
      "name": "Euro"
    },
    "transactionAmount": "2199",
    "transactionCurrency": {
      "symbol": "£",
      "code": "GBP",
      "decimals": 2,
      "name": "British Pound"
    },
    "transactionType": "00",
    "cardToken": "4532********1234",
    "transactions": [
      {
        "status": "ExecSuccess",
        "to": "0x1234567890abcdef1234567890abcdef12345678",
        "value": "2550000000000000000000",
        "data": "0xa9059cbb",
        "hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
      }
    ]
  }
]

Transactions

List Card Transactions

Retrieves paginated transactions for all activated cards of the authenticated user.

Returns three types of transaction events:

Payment: Regular card transactions (purchases, ATM withdrawals). Can appear immediately after authorization with isPending: true, then update when cleared.
Refund: Money returned to your account (product returns, cancellations). Only appears after both authorization and clearing are processed.
Reversal: Cancellation of previous transactions due to technical issues or merchant corrections. Can appear immediately after authorization-level reversals.

The final number might differ slightly, as one thread might contain multiple transactions.

GET

api

cards

transactions

List Card Transactions

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.valox.co/api/v1/cards/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "createdAt": "2024-01-15T14:30:00Z",
    "clearedAt": null,
    "isPending": true,
    "kind": "Payment",
    "status": "Approved",
    "country": {
      "name": "United Kingdom",
      "numeric": "826",
      "alpha2": "GB",
      "alpha3": "GBR"
    },
    "mcc": "5411",
    "merchant": {
      "name": "TESCO STORES",
      "city": "LONDON",
      "country": {
        "name": "United Kingdom",
        "alpha2": "GB"
      }
    },
    "billingAmount": "2550",
    "billingCurrency": {
      "symbol": "€",
      "code": "EUR",
      "decimals": 2,
      "name": "Euro"
    },
    "transactionAmount": "2199",
    "transactionCurrency": {
      "symbol": "£",
      "code": "GBP",
      "decimals": 2,
      "name": "British Pound"
    },
    "transactionType": "00",
    "cardToken": "4532********1234",
    "transactions": [
      {
        "status": "ExecSuccess",
        "to": "0x1234567890abcdef1234567890abcdef12345678",
        "value": "2550000000000000000000",
        "data": "0xa9059cbb",
        "hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
      }
    ]
  }
]

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

cardTokens

string

Comma-separated list of card tokens

limit

integer

default:100

Maximum number of transactions to return

Required range: x >= 10

offset

integer

default:0

Number of transactions to skip

Required range: x >= 0

before

string<date-time>

Filter transactions before this date (ISO 8601 format, e.g., "2023-04-01T00:00:00Z")

after

string<date-time>

Filter transactions after this date (ISO 8601 format, e.g., "2023-03-01T00:00:00Z")

billingCurrency

string

Filter by billing currency code

transactionCurrency

string

Filter by transaction currency code

mcc

string

Filter by Merchant Category Code (MCC)

transactionType

string

Filter by transaction type code (e.g., "00" for Purchase, "01" for Withdrawal)

Response

Successful response with paginated transaction events

count

integer

Total number of transactions available

Example:

25

string | null

URL for the next page of results, null if no more pages

Example:

"/api/v1/cards/transactions?limit=100&offset=100"

string | null

URL for the previous page of results, null if on first page

Example:

null

results

object[]

Array of transaction events for the current page

Option 1
Option 2
Option 3

Show child attributes

results.threadId

string

Thread ID for the transaction

Example:

"1234567890"

results.createdAt

string<date-time>

results.clearedAt

string<date-time> | null

Date of the latest clearing record of the transaction

results.country

object

Show child attributes

results.country.name

string

results.country.numeric

string

results.country.alpha2

string

results.country.alpha3

string

results.isPending

boolean

Whether the transaction is pending settlement.

For Payments: true when authorized but not yet cleared, false when settled
For Refunds: can be true if additional clearing steps are pending, typically false since they require both auth + clearing to appear
For Reversals: typically false as they're usually processed quickly

results.mcc

string

results.merchant

object

Show child attributes

results.merchant.name

string

results.merchant.city

string

results.merchant.country

object

Show child attributes

results.merchant.country.name

string

results.merchant.country.numeric

string

results.merchant.country.alpha2

string

results.merchant.country.alpha3

string

results.billingAmount

string

A BigInt value represented as a string

results.billingCurrency

object

Show child attributes

results.billingCurrency.symbol

string

results.billingCurrency.code

string

results.billingCurrency.decimals

integer

results.billingCurrency.name

string

results.transactionAmount

string

A BigInt value represented as a string

results.transactionCurrency

object

Show child attributes

results.transactionCurrency.symbol

string

results.transactionCurrency.code

string

results.transactionCurrency.decimals

integer

results.transactionCurrency.name

string

results.transactionType

string

First 2 digits of the DE3 field (ISO 8583), representing the transaction type code. Common values include (not limited to):

"00": Purchase (POS)
"01": Withdrawal (ATM)
"10": Account Funding
"20": Return of Goods
"28": Prepaid Load
"30": Balance Inquiry
"70": PIN Change
"72": PIN Unblock

results.cardToken

string

The token identifying the card used for this transaction

results.transactions

object[]

Show child attributes

results.transactions.status

enum<string>

Available options:

Unsubmitted,

Unconfirmed,

ExecReverted,

ExecSuccess

results.transactions.to

string

results.transactions.value

string

A BigInt value represented as a string

results.transactions.data

string

results.transactions.hash

string | null

results.kind

enum<string>

Available options:

Payment

results.status

enum<string>

Available options:

Approved,

IncorrectPin,

InsufficientFunds,

ExceedsApprovalAmountLimit,

InvalidAmount,

PinEntryTriesExceeded,

IncorrectSecurityCode,

Reversal,

PartialReversal,

Other

Link physical card to user Dispute a Transaction

⌘I

Authentication

API reference

PSE API

List Card Transactions

Authorizations

Query Parameters

Response