Skip to main content
Cards is available in sandbox only while we finish development. Dakota enables Cards per account. The Cards endpoints are in the API reference, marked Sandbox only. Endpoints, fields, and flows can still change before release.
Sandbox runs the real card code: authorizations are decided as in production, holds land on the wallet, and the same webhooks fire. Only the trigger is simulated. A simulation call stands in for the merchant and the card network.

1. Set up

  1. Ask Dakota to activate Cards on your sandbox account. No agreements are needed.
  2. Approve the customer’s onboarding with POST /sandbox/simulate/onboarding and type: kyb_approve, for an individual or a business. Set applicant_id to the customer’s application_id. The customer’s status and kyc_status then read approved. Do not use kyc_approve for this: it changes only the application status.
  3. Activate a customer. You act as the customer: open the terms link and accept it yourself.
  4. 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.
It returns a 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:
The call returns 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.
  • type is authorization (default), credit_authorization (a credit to the card), financial_authorization (clears immediately), or balance_inquiry (moves no funds, takes no amount). A balance_inquiry creates no card transaction and fires no card_transaction.* webhook. Once the network approves it, the simulation completes with no card_transaction_id: the response reads status: completed, or pending if the answer has not arrived yet, and the simulation then reads state_position: completed, with completed_at set. A declined balance inquiry answers pending and fails the simulation: polling it reads state: rejected and state_position: failed, with the network’s reason in metadata.failure_reason.
  • partial_approval_capable: true simulates a merchant that accepts a partial approval.
  • A decline is not an HTTP error. It creates a card transaction with status: declined and a decline_reason. To trigger one, simulate a purchase on an unfunded wallet.
  • A card that is not active cannot present a purchase: the call returns 409 card-not-active.
A declined purchase is a simulation like any other: it reads 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.