1. Set up
- Ask Dakota to activate Cards on your sandbox account. No agreements are needed.
- Approve the customer’s onboarding with
POST /sandbox/simulate/onboardingandtype: kyb_approve, for an individual or a business. Setapplicant_idto the customer’sapplication_id. The customer’sstatusandkyc_statusthen readapproved. Do not usekyc_approvefor this: it changes only the application status. - Activate a customer. You act as the customer: open the terms link and accept it yourself.
- Create a cardholder, enable a wallet, and create a card. These steps are the same as in production.
2. Fund the wallet
POST /sandbox/wallets/{wallet_id}/faucet sends testnet RD to the wallet on Base Sepolia, through the normal deposit path.
simulation_id. Poll GET /sandbox/simulations/{simulation_id} until state_position is completed, which is also when completed_at is set. state reads accepted while the faucet runs and after it succeeds, so do not wait on it. A failed faucet reads state: rejected and state_position: failed: call the faucet again with a new idempotency key. Then check card.available on GET /wallets/{wallet_id}/balances before you simulate a purchase.
A hold can be larger than the purchase, so fund more than you plan to spend. Two faucet calls cover a 2 USD purchase.
3. Simulate a purchase
POST /sandbox/cards/simulate/transaction:
202 with a simulation, and card_transaction.created fires. With status: completed it names the card_transaction_id. With status: pending the transaction is not visible yet and the response has no card_transaction_id: poll GET /sandbox/simulations/{simulation_id} until it names one.
typeisauthorization(default),credit_authorization(a credit to the card),financial_authorization(clears immediately), orbalance_inquiry(moves no funds, takes noamount). Abalance_inquirycreates no card transaction and fires nocard_transaction.*webhook. Once the network approves it, the simulation completes with nocard_transaction_id: the response readsstatus: completed, orpendingif the answer has not arrived yet, and the simulation then readsstate_position: completed, withcompleted_atset. A declined balance inquiry answerspendingand fails the simulation: polling it readsstate: rejectedandstate_position: failed, with the network’s reason inmetadata.failure_reason.partial_approval_capable: truesimulates a merchant that accepts a partial approval.- A decline is not an HTTP error. It creates a card transaction with
status: declinedand adecline_reason. To trigger one, simulate a purchase on an unfunded wallet. - A card that is not
activecannot present a purchase: the call returns409 card-not-active.
state: accepted and names the declined card_transaction_id. Rarely, a decline cannot be recorded as a card transaction. The simulation then stays open for a short while with no card_transaction_id, and afterwards reads state: rejected and state_position: failed, with the network result in metadata.failure_reason, such as declined:INSUFFICIENT_FUNDS.
4. Advance the purchase
POST /sandbox/cards/simulate/transaction/{card_transaction_id}:
A known sandbox limitation: after
update_amount, the transaction’s auth_amount adds the new total to the original amount rather than replacing it, and the wallet hold is not raised. Settlement follows the new total.
completed on an advance means the action was accepted, and the response names the transaction it applies to. Reading the transaction, and card_transaction.updated, can follow later: almost at once for clear and expire, and 30 seconds or more in sandbox for void and return_reversal. Wait for the webhook, or poll GET /card_transactions/{card_transaction_id}, rather than reading the transaction straight after the call.
In sandbox, the card network can refuse return_reversal: it has answered “Return reversal is not supported for debit transactions”. The call then returns 422 sandbox-invalid-action-for-transaction, and the transaction does not change.
A return is a new transaction on the same card, and the response names it. If the response is status: pending, poll the simulation for it, as for a purchase. To reverse the return, advance that new transaction.
After a clear, the transaction reads cleared, but the wallet’s card.held keeps counting the cleared amount until a settlement sweep collects it: see Card funding. No sweep runs on its own in sandbox, so the amount stays held. Contact Dakota if you need a sandbox wallet swept.
Limits
Simulation endpoints return
403 in production.
