Skip to main content
POST
Simulate a card authorization

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.

Body

application/json

A request to present a simulated authorization on a card.

ā€‹
card_id
string
required

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"

ā€‹
amount
string

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.

Example:

"2.00"

ā€‹
merchant
object

The merchant presenting a simulated card transaction.

ā€‹
type
enum<string>
default:authorization

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, and it creates no card transaction: no card_transaction.* webhook fires, and the simulation completes with no card_transaction_id. A declined one answers pending and fails the simulation (state: rejected).

Available options:
authorization,
credit_authorization,
financial_authorization,
balance_inquiry
Example:

"authorization"

ā€‹
partial_approval_capable
boolean

Whether the merchant accepts a partial approval. Partial approvals are not returned yet: a purchase whose hold exceeds the available balance is declined either way.

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"