curl --request PATCH \
--url https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction/{card_transaction_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-idempotency-key: <x-idempotency-key>' \
--data '
{
"action": "clear",
"amount": "2.00"
}
'const options = {
method: 'PATCH',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({action: 'clear', amount: '2.00'})
};
fetch('https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction/{card_transaction_id}', 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/{card_transaction_id}"
payload = {
"action": "clear",
"amount": "2.00"
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(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/{card_transaction_id}"
payload := strings.NewReader("{\n \"action\": \"clear\",\n \"amount\": \"2.00\"\n}")
req, _ := http.NewRequest("PATCH", 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_01J8ZQ4T7K2M9Y",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Card Transaction not found",
"status": 404,
"detail": "Card Transaction not found",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#conflict",
"title": "Conflict",
"status": 409,
"detail": "idempotency key already used with different parameters or on another sandbox simulation",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#sandbox-invalid-action-for-transaction",
"title": "Sandbox Invalid Action For Transaction",
"status": 422,
"detail": "action update_amount requires an amount",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}Advance a simulated card transaction (deprecated, use POST)
Deprecated: use POST on this same path. PATCH remains available
and behaves identically, but new integrations should call POST.
Moves a simulated card transaction through the rest of its lifecycle. Each action produces the same records and webhooks the network would produce in production.
| Action | Effect | Amount |
|---|---|---|
clear | Settles the authorization. | Optional, for a partial or over-capture clearing. |
void | Releases the authorization without settling it. | Optional, for a partial reversal. |
expire | Lets the authorization lapse. | Not used. |
update_amount | Increments or decrements the held amount. | Required. |
return | Refunds the cardholder. | Required. |
return_reversal | Reverses a return. | Not used. |
A return is a standalone transaction on the same card rather than a state of the original authorization, so the response names the new return transaction. Target that transaction to reverse the return.
Available in sandbox mode only.
curl --request PATCH \
--url https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction/{card_transaction_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-idempotency-key: <x-idempotency-key>' \
--data '
{
"action": "clear",
"amount": "2.00"
}
'const options = {
method: 'PATCH',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({action: 'clear', amount: '2.00'})
};
fetch('https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction/{card_transaction_id}', 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/{card_transaction_id}"
payload = {
"action": "clear",
"amount": "2.00"
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(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/{card_transaction_id}"
payload := strings.NewReader("{\n \"action\": \"clear\",\n \"amount\": \"2.00\"\n}")
req, _ := http.NewRequest("PATCH", 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_01J8ZQ4T7K2M9Y",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Card Transaction not found",
"status": 404,
"detail": "Card Transaction not found",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#conflict",
"title": "Conflict",
"status": 409,
"detail": "idempotency key already used with different parameters or on another sandbox simulation",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#sandbox-invalid-action-for-transaction",
"title": "Sandbox Invalid Action For Transaction",
"status": 422,
"detail": "action update_amount requires an amount",
"instance": "https://api.platform.dakota.xyz/sandbox/cards/simulate/transaction/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"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/2ZFHrqBHb3cTfLVkFSGmHZqdDPi",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}Authorizations
Headers
Unique key (UUID) to ensure request idempotency on POST, PUT and PATCH requests.
A key is scoped to your client, the HTTP method and the path, and is remembered for 24 hours after a
successful (below 400) response. Repeating the same request (same JSON body, whatever the key order or
whitespace) with the same key within that window returns the original response with
X-Idempotent-Replayed: true instead of executing the request again. Using the same key on the same
endpoint with a different body returns 422 with problem type idempotency-key-reused; the request is
not executed. Error responses (4xx and 5xx) are not remembered, so a request refused for a fixable reason
can be corrected and retried under the same key. Request bodies that are not JSON (for example file
uploads) are not compared.
Path Parameters
Card transaction to advance. 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"
Body
An action that advances a simulated card transaction.
How to advance the transaction. update_amount and return
require an amount; clear and void take one only for a partial
amount; expire and return_reversal take none, and an amount
supplied alongside either is refused.
clear, void, expire, update_amount, return, return_reversal "clear"
Amount in decimal USD, at most two decimal places. Capped by the sandbox per-transaction limit.
"2.00"
The merchant presenting a simulated card transaction.
Show child attributes
Show child attributes
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 creates a card transaction with
status: declined, so it completes here and names it the same as an
approval. Only a decline that could not be recorded as a card
transaction (rare) fails the simulation; its outcome is on
GET /sandbox/simulations/{simulation_id} (state: rejected).
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?