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.

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

"authorization"

ā€‹
partial_approval_capable
boolean

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_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. 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).

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"