Skip to main content
POST
Advance a simulated card transaction

Authorizations

ā€‹
x-api-key
string
header
required

Headers

ā€‹
x-idempotency-key
string<uuid>
required

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_id
string
required

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: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

Body

application/json

An action that advances a simulated card transaction.

ā€‹
action
enum<string>
required

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. The update_amount amount is the authorization's new total, not a change to it.

merchant is used only by return, and only its descriptor: the card network takes no other merchant detail for a refund, so the refund's merchant category and location are the network's own. Without a descriptor a return takes the purchase's. The rest of merchant, and merchant on every other action, does not change the result, though it still counts toward the X-Idempotency-Key request match.

Available options:
clear,
void,
expire,
update_amount,
return,
return_reversal
Example:

"clear"

ā€‹
amount
string

Amount in decimal USD, at most two decimal places. Capped by the sandbox per-transaction limit.

Example:

"2.00"

ā€‹
merchant
object

The merchant presenting a simulated card transaction.

Response

Card simulation accepted

An accepted card simulation.

ā€‹
simulation_id
string
required

Simulation identifier. Resolve it with GET /sandbox/simulations/{simulation_id}.

Example:

"sim_card_01J8ZQ4T7K2M9X"

ā€‹
status
enum<string>
required

Where a card simulation stands. completed means the card transaction exists and this response names it, or, for a balance_inquiry, that the network approved the inquiry: an inquiry moves no funds and creates no card transaction, so it completes with no card_transaction_id. pending means the simulation was accepted and its outcome is not on this response: the transaction has not been materialized yet, the inquiry has not been answered yet, or the simulation was declined with no card transaction to name. Poll GET /sandbox/simulations/{simulation_id} for the identifier, for state_position: completed, or for state: rejected. A declined card authorization creates a card transaction with status: declined, so it completes here and names it the same as an approval. A decline with no card transaction answers pending here and fails the simulation, which then reads state: rejected with the reason in metadata.failure_reason: a declined balance_inquiry, or a decline that could not be recorded as a card transaction (rare). 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.

Available options:
pending,
completed,
failed
ā€‹
card_transaction_id
string

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"