curl --request GET \
--url https://api.platform.sandbox.dakota.xyz/card_transactions/{card_transaction_id} \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.platform.sandbox.dakota.xyz/card_transactions/{card_transaction_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.platform.sandbox.dakota.xyz/card_transactions/{card_transaction_id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.platform.sandbox.dakota.xyz/card_transactions/{card_transaction_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"card_id": "2tQRvvnYkN6edEJUTmF1LzTj2ug",
"customer_id": "2tQRvD3xFcJ7bKpW9qNsT4hZmYr",
"status": "cleared",
"auth_amount": "39",
"cleared_amount": "39",
"outstanding_amount": "0",
"currency": "USD",
"merchant_descriptor": "COFFEE ROASTERS",
"merchant_mcc": "5814",
"merchant_city": "BROOKLYN",
"merchant_country": "USA",
"created_at": 1758211200,
"updated_at": 1758297660,
"completed_at": 1758297660
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}Get a card transaction
Get details for a specific card transaction by ID.
curl --request GET \
--url https://api.platform.sandbox.dakota.xyz/card_transactions/{card_transaction_id} \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.platform.sandbox.dakota.xyz/card_transactions/{card_transaction_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.platform.sandbox.dakota.xyz/card_transactions/{card_transaction_id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.platform.sandbox.dakota.xyz/card_transactions/{card_transaction_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"card_id": "2tQRvvnYkN6edEJUTmF1LzTj2ug",
"customer_id": "2tQRvD3xFcJ7bKpW9qNsT4hZmYr",
"status": "cleared",
"auth_amount": "39",
"cleared_amount": "39",
"outstanding_amount": "0",
"currency": "USD",
"merchant_descriptor": "COFFEE ROASTERS",
"merchant_mcc": "5814",
"merchant_city": "BROOKLYN",
"merchant_country": "USA",
"created_at": 1758211200,
"updated_at": 1758297660,
"completed_at": 1758297660
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}Path Parameters
Response
Card transaction details
A card transaction: one purchase, refund or other card-network event, across its whole life from authorization to settlement.
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.
pending, authorized, partially_cleared, cleared, auth_reversed, expired, returned, disputed, force_posted, declined "authorized"
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.
"42.5"
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.
"10.5"
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.
"49.5"
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.
"42.5"
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.
pending, paid, reversed, failed "pending"
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.
insufficient_funds, card_inactive, spend_limit_exceeded, merchant_not_allowed, card_details_incorrect, suspected_fraud, authorization_timeout, other "insufficient_funds"
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.
hold_adjustment "hold_adjustment"
Was this page helpful?

