Skip to main content
GET
Get a card transaction
Sandbox only. This endpoint is available in sandbox only while we finish development. It is not available in production yet, and its request and response shapes may change before release.

Authorizations

x-api-key
string
header
required

Path Parameters

card_transaction_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

Response

Card transaction details

A card transaction: one purchase, refund or other card-network event, across its whole life from authorization to settlement.

id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

card_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

customer_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

status
enum<string>
required

Current status of the card transaction. pending is the initial state before the first authorization event arrives. cleared/partially_cleared describe settled funds movement. returned is the status of a merchant refund, which is usually its own card transaction on the same card while the original purchase stays cleared. A refund can also land on the purchase's own transaction: it then keeps its purchase status while the refund is partial, and becomes returned, with cleared_amount still set, once the refunds cover everything that cleared and nothing authorized is left to clear (a refunded first instalment stays partially_cleared). A standalone refund reversed in full becomes auth_reversed. Do not detect refunds from status; a transaction carries a refund whenever refund_state has a value. disputed is reserved and not emitted yet. declined means the authorization was refused and moved no money; read decline_reason and decline_code for why.

Available options:
pending,
authorized,
partially_cleared,
cleared,
auth_reversed,
expired,
returned,
disputed,
force_posted,
declined
Example:

"authorized"

cleared_amount
string
required

The settled amount, in major currency units, as a decimal string without trailing zeros. May differ from auth_amount and may arrive across multiple partial clearings.

Example:

"42.5"

outstanding_amount
string
required

The part of cleared_amount that no authorization covered, less any refunds, in major currency units, as a decimal string without trailing zeros: non-zero after a force post, or when a merchant clears more than it authorized.

Example:

"0"

currency
string
required

ISO 4217 currency code.

Example:

"USD"

created_at
integer
required

Unix timestamp (seconds) when Dakota first recorded this transaction.

updated_at
integer
required

Unix timestamp (seconds) of last update.

auth_amount
string | null

The authorized purchase amount, in major currency units, as a decimal string without trailing zeros ("42.5", "2", "0"). In some merchant categories, and for purchases in a non-USD currency, the hold placed on the wallet is larger than this amount until the transaction clears; the wallet's card balance held includes it. On a declined transaction it is the amount that was attempted, and nothing is held. Null only for a force-posted transaction, which arrives with no matching authorization.

Example:

"42.5"

returned_amount
string | null

How much has been refunded on this transaction, in major currency units, as a decimal string without trailing zeros: the total of every merchant refund on it, less any refund the merchant later reversed. Set whenever the transaction carries a refund (refund_state has a value), whatever its status: usually returned, but also cleared, partially_cleared or force_posted for a refund on the purchase's own transaction, and auth_reversed for a standalone refund reversed in full. Updated on each card_transaction.updated as further refunds or reversals arrive, so it can go up or down. "0" once every refund on it was reversed; refund_state is then reversed, or stays paid if the refund had already been paid out. Null when the transaction is not a refund, and on a refund whose amount has not been received yet, for example one made before this field existed, until it is filled in by a card_transaction.updated. Says nothing about payout; read refund_state for whether the money reached the customer's wallet.

Example:

"10.5"

hold_amount
string | null

The amount reserved from the wallet's available balance for this purchase, in major currency units, as a decimal string without trailing zeros: the purchase plus any merchant-category hold, or the +3% hold on a purchase in a non-USD currency. The reservation is released when the transaction clears, is reversed or expires; this field keeps the amount. On a declined purchase, the amount that would have been reserved. Null for credits and force posts, and for a transaction recorded before this field existed.

Example:

"49.5"

merchant_descriptor
string | null

Raw merchant descriptor as reported by the card network.

merchant_category
string | null

Merchant category, derived from the merchant category code.

merchant_mcc
string | null

Merchant category code (MCC).

merchant_city
string | null

Merchant city as reported by the card network.

merchant_state
string | null

Merchant state or region as reported by the card network.

authorization_code
string | null

Approval code the card issuer returned for the authorization.

merchant_amount
string | null

What the transaction amounts to in merchant_currency, as a decimal string in major units (for example "42.5"). It is a non-negative magnitude: what cleared, gross of any refund (as cleared_amount is), once anything has cleared; otherwise what was authorized (a reversed or expired authorization keeps reporting what it authorized, as auth_amount does); for a refund on its own, what was refunded less any reversal; and for a declined purchase, what was attempted. Descriptive only: it is not comparable with, and must not be added to, the USD amounts on this transaction.

Example:

"42.5"

merchant_currency
string | null

ISO 4217 code of the merchant's currency, the currency of merchant_amount. USD for a domestic purchase.

Example:

"EUR"

merchant_country
string | null

Merchant country as reported by the card network.

entry_mode
enum<string> | null

How the card was presented. online covers every card-not-present purchase: e-commerce, in-app, card on file, and mail or phone order. Null when not known.

Available options:
contactless,
in_store,
online,
unknown
Example:

"contactless"

wallet_type
enum<string> | null

The digital wallet the purchase was made through. merchant is a token held by the merchant. Null when the card itself was used, or when not known.

Available options:
apple_pay,
google_pay,
samsung_pay,
merchant,
other
Example:

"apple_pay"

three_ds_result
enum<string> | null

Outcome of 3-D Secure cardholder authentication. Null when no 3-D Secure data was received for the purchase.

Available options:
authenticated,
attempted,
failed,
not_performed
Example:

"authenticated"

conversion_rate
string | null

Decimal string: the rate from merchant_currency to the card's currency, fixed when the transaction was first seen. "1" for a domestic purchase. Null when not known.

Example:

"1.0825"

settlement_date
string<date> | null

Network settlement date of the transaction's first settled amount. It becomes known after the purchase, usually a day after clearing, and is null until then.

Example:

"2026-11-12"

events
Card Transaction Network Event · object[] | null

The card transaction's network events, approved ones only, oldest first, so a decline shows through status and decline_reason instead. Null until an event carries it.

network
string | null

Card network that processed the transaction.

refund_state
enum<string> | null

How far a refund has actually progressed. Deliberately separate from status: status: returned means the card network returned the money, while refund_state: paid means it reached the customer's wallet. Both can be true at once and they answer different questions — do not treat status: returned alone as proof the customer has been paid. A transaction carries a refund whenever this has a value, whatever its status. Null when the transaction is not a refund; webhook payloads leave the key out instead. pending: the refund is owed and has not reached the wallet yet. paid: it reached the customer's wallet. Stays paid even if the merchant later reverses the refund; returned_amount then goes down. reversed: every refund on the transaction was cancelled before it was paid out, so nothing is owed. failed: the payout to the wallet failed and needs action. With several refunds on one transaction, this reports the one that most needs attention, in this order: pending, failed, paid, reversed.

Available options:
pending,
paid,
reversed,
failed
Example:

"pending"

decline_reason
enum<string> | null

Why a declined authorization was refused. Null unless status is declined. insufficient_funds: the wallet's available balance was lower than the purchase's hold, which in some merchant categories, and for purchases in a non-USD currency, is larger than auth_amount. Also returned when the authorization could not be evaluated, for example during a service disruption; a retry can then succeed. card_inactive: the card was not active (e.g. frozen or not yet activated). spend_limit_exceeded: the purchase would have exceeded the card's spend limit. A per_transaction limit is checked against the purchase amount, not the hold: a purchase strictly over it is declined, and one exactly at it is allowed. merchant_not_allowed: a merchant or category restriction on the card refused this merchant. card_details_incorrect: the card number, expiry, or CVV presented did not match the card on file. suspected_fraud: the authorization was refused as suspected fraud. authorization_timeout: the authorization request timed out before a decision was reached. other: a reason not covered above, including one the card provider added after this list was written — an unrecognized reason from the card provider is reported as other rather than omitted, so this field is forward compatible.

Available options:
insufficient_funds,
card_inactive,
spend_limit_exceeded,
merchant_not_allowed,
card_details_incorrect,
suspected_fraud,
authorization_timeout,
other
Example:

"insufficient_funds"

decline_code
string | null

The raw network/processor code behind a decline, for support diagnostics. Null unless status is declined. Values can change upstream; do not branch on it — use decline_reason for that.

Example:

"INSUFFICIENT_FUNDS"

decline_detail
enum<string> | null

Narrows decline_reason. hold_adjustment: the purchase alone fit the wallet's available balance; its merchant-category or currency hold did not, so hold_amount is the amount that could not be reserved. Null unless status is declined, and null on a decline that has no detail.

Available options:
hold_adjustment
Example:

"hold_adjustment"

completed_at
integer | null

Unix timestamp (seconds) when the transaction reached a settled state, if it has.