Advance a simulated card transaction
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"
}Sandbox
Advance a simulated card transaction
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.
PATCH
/
sandbox
/
cards
/
simulate
/
transaction
/
{card_transaction_id}
Advance a simulated card transaction
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 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.
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.
Required string length:
27Pattern:
^[0-9A-Za-z]{27}$Example:
"1NFHrqBHb3cTfLVkFSGmHZqdDPi"
Body
application/json
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.
Available options:
clear, void, expire, update_amount, return, return_reversal Example:
"clear"
Amount in decimal USD, at most two decimal places. Capped by the sandbox per-transaction limit.
Example:
"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}.
Example:
"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.
Available options:
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.
Required string length:
27Pattern:
^[0-9A-Za-z]{27}$Example:
"1NFHrqBHb3cTfLVkFSGmHZqdDPi"
Was this page helpful?