curl --request POST \
--url https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-idempotency-key: <x-idempotency-key>' \
--data '
{
"card_id": "1NFHrqBHb3cTfLVkFSGmHZqdDPi",
"amount": "2.00",
"merchant": {
"descriptor": "COFFEE ROASTERS",
"mcc": "5814",
"city": "BROOKLYN",
"state": "NY",
"country": "USA"
},
"type": "authorization"
}
'const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
card_id: '1NFHrqBHb3cTfLVkFSGmHZqdDPi',
amount: '2.00',
merchant: {
descriptor: 'COFFEE ROASTERS',
mcc: '5814',
city: 'BROOKLYN',
state: 'NY',
country: 'USA'
},
type: 'authorization'
})
};
fetch('https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction"
payload = {
"card_id": "1NFHrqBHb3cTfLVkFSGmHZqdDPi",
"amount": "2.00",
"merchant": {
"descriptor": "COFFEE ROASTERS",
"mcc": "5814",
"city": "BROOKLYN",
"state": "NY",
"country": "USA"
},
"type": "authorization"
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction"
payload := strings.NewReader("{\n \"card_id\": \"1NFHrqBHb3cTfLVkFSGmHZqdDPi\",\n \"amount\": \"2.00\",\n \"merchant\": {\n \"descriptor\": \"COFFEE ROASTERS\",\n \"mcc\": \"5814\",\n \"city\": \"BROOKLYN\",\n \"state\": \"NY\",\n \"country\": \"USA\"\n },\n \"type\": \"authorization\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"simulation_id": "sim_card_01J8ZQ4T7K2M9X",
"card_transaction_id": "2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"status": "completed"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#invalid-request",
"title": "Invalid request",
"status": 400,
"detail": "amount must be a positive decimal with at most two decimal places",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#forbidden",
"title": "Forbidden",
"status": 403,
"detail": "Endpoint only available in sandbox mode",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Card not found",
"status": 404,
"detail": "Card not found",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#card-not-active",
"title": "Card Not Active",
"status": 409,
"detail": "The card must be active to present a simulated transaction.",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#sandbox-amount-cap-exceeded",
"title": "Sandbox Amount Cap Exceeded",
"status": 422,
"detail": "amount 25 exceeds sandbox cap of 2; reduce the amount and retry",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#sandbox-card-simulation-daily-limit",
"title": "Sandbox Card Simulation Daily Limit",
"status": 429,
"detail": "This client has used its card-simulation allowance for the day. Retry within 24 hours.",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#internal-error",
"title": "Internal Error",
"status": 500,
"detail": "An internal error occurred",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-implemented",
"title": "Not Implemented",
"status": 501,
"detail": "card simulation is not available in this deployment yet",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#provider-error",
"title": "Provider Error",
"status": 502,
"detail": "provider sandbox service returned an error",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}Simulate a card authorization
Presents a card authorization to Dakota as if a merchant had swiped the
card. The authorization runs the production path: the authorization
service decides it, the hold lands on the wallet, and the
card_transaction.created webhook fires. Only the trigger is synthetic.
A decline is a normal outcome, not an HTTP error. A card with too little
spendable balance produces a card_transaction carrying the real
decline result, so read the transaction rather than the status code to
learn whether the authorization was approved.
An authorization holds more than its own amount. The hold carries a buffer for network adjustments, so a 2 USD authorization needs about 2.60 USD of spendable balance. Fund the wallet with two faucet calls before you simulate a 2 USD purchase.
The card must belong to a customer of the authenticated client. Available in sandbox mode only.
curl --request POST \
--url https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-idempotency-key: <x-idempotency-key>' \
--data '
{
"card_id": "1NFHrqBHb3cTfLVkFSGmHZqdDPi",
"amount": "2.00",
"merchant": {
"descriptor": "COFFEE ROASTERS",
"mcc": "5814",
"city": "BROOKLYN",
"state": "NY",
"country": "USA"
},
"type": "authorization"
}
'const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
card_id: '1NFHrqBHb3cTfLVkFSGmHZqdDPi',
amount: '2.00',
merchant: {
descriptor: 'COFFEE ROASTERS',
mcc: '5814',
city: 'BROOKLYN',
state: 'NY',
country: 'USA'
},
type: 'authorization'
})
};
fetch('https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction"
payload = {
"card_id": "1NFHrqBHb3cTfLVkFSGmHZqdDPi",
"amount": "2.00",
"merchant": {
"descriptor": "COFFEE ROASTERS",
"mcc": "5814",
"city": "BROOKLYN",
"state": "NY",
"country": "USA"
},
"type": "authorization"
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction"
payload := strings.NewReader("{\n \"card_id\": \"1NFHrqBHb3cTfLVkFSGmHZqdDPi\",\n \"amount\": \"2.00\",\n \"merchant\": {\n \"descriptor\": \"COFFEE ROASTERS\",\n \"mcc\": \"5814\",\n \"city\": \"BROOKLYN\",\n \"state\": \"NY\",\n \"country\": \"USA\"\n },\n \"type\": \"authorization\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"simulation_id": "sim_card_01J8ZQ4T7K2M9X",
"card_transaction_id": "2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"status": "completed"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#invalid-request",
"title": "Invalid request",
"status": 400,
"detail": "amount must be a positive decimal with at most two decimal places",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#forbidden",
"title": "Forbidden",
"status": 403,
"detail": "Endpoint only available in sandbox mode",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Card not found",
"status": 404,
"detail": "Card not found",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#card-not-active",
"title": "Card Not Active",
"status": 409,
"detail": "The card must be active to present a simulated transaction.",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#sandbox-amount-cap-exceeded",
"title": "Sandbox Amount Cap Exceeded",
"status": 422,
"detail": "amount 25 exceeds sandbox cap of 2; reduce the amount and retry",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#sandbox-card-simulation-daily-limit",
"title": "Sandbox Card Simulation Daily Limit",
"status": 429,
"detail": "This client has used its card-simulation allowance for the day. Retry within 24 hours.",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#internal-error",
"title": "Internal Error",
"status": 500,
"detail": "An internal error occurred",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-implemented",
"title": "Not Implemented",
"status": 501,
"detail": "card simulation is not available in this deployment yet",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#provider-error",
"title": "Provider Error",
"status": 502,
"detail": "provider sandbox service returned an error",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}Authorizations
Headers
Unique key to ensure request idempotency. If the same key is used within a certain time window, the original response will be returned instead of executing the request again.
Body
A request to present a simulated authorization on a card.
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.
27^[0-9A-Za-z]{27}$"1NFHrqBHb3cTfLVkFSGmHZqdDPi"
Amount in decimal USD, at most two decimal places. Capped by the sandbox per-transaction limit.
Required for every type except balance_inquiry, which moves no
funds and so takes no amount: omit it, or send "0". A
balance_inquiry naming a non-zero amount is refused.
"2.00"
The merchant presenting a simulated card transaction.
Show child attributes
Show child attributes
Which network message the simulation opens. authorization is a
standard purchase; financial_authorization clears immediately;
balance_inquiry checks the spendable balance and moves no funds,
so it is the one type that takes no amount.
authorization, credit_authorization, financial_authorization, balance_inquiry "authorization"
Whether the merchant accepts a partial approval. A merchant that does gets an approval for the available balance instead of a decline.
Response
Card simulation accepted
An accepted card simulation.
Simulation identifier. Resolve it with
GET /sandbox/simulations/{simulation_id}.
"sim_card_01J8ZQ4T7K2M9X"
Where a card simulation stands. completed means the card transaction
exists and this response names it. pending means the simulation was
accepted but the transaction has not been materialized yet; poll
GET /sandbox/simulations/{simulation_id} for the identifier. failed
means the simulation was not accepted: a refusal the endpoint could
classify comes back as a problem response instead, so failed is what
an unclassified one looks like. It can still name a card transaction,
because the response reports whichever transaction the call resolved.
A declined card authorization is not a failed simulation: the
simulation succeeded and the decline arrives on the card transaction.
pending, completed, failed 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.
27^[0-9A-Za-z]{27}$"1NFHrqBHb3cTfLVkFSGmHZqdDPi"
Was this page helpful?