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.
Each recipe lists the calls in order, what to wait for, and the refusals worth handling. Every call links to its API reference page, which has the full request and response. Common to every call:
  • Host: https://api.platform.sandbox.dakota.xyz. Cards is sandbox only for now.
  • Authenticate with your API key in the x-api-key header.
  • Send an X-Idempotency-Key (a UUID) on every POST, PATCH, and PUT, except POST /cards/{card_id}/reveal_session. A key is scoped to the method and path, and kept for 24 hours. Retrying with the same key and body replays the first response if it succeeded; after an error, the retry runs again. Once a key has succeeded, sending it with a different body returns 422 idempotency-key-reused.
  • Webhooks arrive on your existing stream, in the standard envelope. If your webhook target filters by event_types, add the card event types first. See Cards webhooks.

Setup

1. Activate a customer for Cards

Once per customer. Dakota must have activated your account first. That step has no API; ask your Dakota contact.
  1. GET /customers/{customer_id}/capabilities. Find the entry with capability: "cards".
  2. If its status is action_required, send the customer the url of its terms_acceptance requirement. Read the requirement’s key rather than assuming one: a business accepts cards_tos, and an individual may be asked for cards_consumer_tos. The customer accepts the terms on a page Dakota hosts.
  3. Wait for customer.capability_status.updated with capability: "cards" and status: "available".
Until then, cardholder, enablement, and card creation return 403 cards-tos-not-accepted, 403 cards-capability-enabling while Dakota finishes the setup (retry once that webhook arrives), or 403 cards-capability-unavailable when more than the terms is outstanding. Details: Activating customers.

2. Create a cardholder

Once per person. Pick the request shape that matches the customer:
  1. For a business customer, GET /customers/{customer_id}/persons. Pick a person whose cardholder_id is null. Collect what missing_for_cards lists: phone when no usable phone is on file, and email when none is on file.
  2. POST /customers/{customer_id}/cardholders. Returns the cardholder with status: "pending".
  3. Wait for cardholder.updated with status: "active". This usually takes seconds.
Handle 409 cardholder-person-exists (the email belongs to another person of this customer: retry with the person_id the error names, if it names one, and otherwise send a different email) and 409 cardholder-already-exists. Details: Cardholders.

3. Enable a wallet for cards

Once per wallet, before its first card. The wallet must be an EVM wallet of the customer the cards are for, with exactly one customer policy that no other wallet uses: see Before you enable a wallet.
  1. Optionally read GET /cards/spend_options and pick the asset and network the wallet’s cards spend. The default is RD on Base, and the choice is fixed once the wallet is enabled: see Choose the spend option.
  2. Have the customer sign the intent {"type": "enable_card_settlement", "wallet_id": "…", "idempotency_key": "…"}, with spend_asset and spend_network_id added when you chose an option, the same way they sign any endorsed request.
  3. POST /wallets/{wallet_id}/card_enablement with the intent and signatures. Usually returns state: "active", and cards can be issued straight away. It can return state: "attaching" instead, when activation has not finished.
  4. wallet.card_enablement.completed fires when the state becomes active, whether in that call or later. Handle both responses. You can also read GET /wallets/{wallet_id}/card_enablement.
Handle 422 card-spend-option-not-allowed, 422 card-spend-option-required and 409 card-spend-option-conflict (the spend option), 422 wallet-family-not-supported (not an EVM wallet; GET returns it too) and 409 card-enablement-precondition (the wallet’s policies need fixing, or Dakota’s setup is incomplete). Details: Wallet enablement.

4. Issue a card

  1. POST /customers/{customer_id}/cards with cardholder_id, wallet_id, and optionally spend_limit, nickname, and external_id. Returns the card with status: "pending".
  2. Wait for card.updated with status: "active". The card can now be revealed and spent.
Handle 403 cardholder-not-active, 403 wallet-not-card-enabled (do recipe 3 first), 400 limit-reached (the cardholder has too many active cards), 409 cardholder-reenroll-required (delete the cardholder and create it again), and 409 wallet-owes-card-debt (the wallet owes Dakota a card debt; contact Dakota support, or retry once it is paid), 409 card-spend-option-conflict and 422 card-spend-option-unavailable (the wallet’s spend option cannot be used for a card; contact Dakota, retrying does not help). Details: Issuing and managing cards.

Using cards

5. Show the card number to the cardholder

  1. In the browser, Cards.js calls your backend when the cardholder asks to see the card.
  2. Your backend authenticates the user and confirms they own the card. Then it calls POST /cards/{card_id}/reveal_session with session_type: "card_details" and the page’s origin. No idempotency key.
  3. Your backend returns the session to Cards.js, which shows the details in a secure frame.
The card must be active. A session works once and expires within minutes. Details: Secure card data.

6. Freeze, unfreeze, or close a card

PATCH /cards/{card_id} with status set to frozen, active, or closed. Wait for card.updated. Closing is permanent. A closed card stays readable with status: "closed", but lists leave it out unless you filter with status=closed. Every change to it, and a reveal, returns 403 card-closed (an unfreeze reports 403 cardholder-suspended first if the cardholder is not active and was not deleted). Closing it again returns 200, and the card stays closed. Keep the card.updated event with status: "closed" as its final record. Unfreezing can be refused: 403 card-freeze-held (a freeze you cannot lift, named in freeze_sources), 403 card-not-activated, 403 cardholder-suspended (the cardholder is not active; the error names its status), or 403 card-closed. An overdrawn card refuses both freezing and unfreezing with 409 card-overdrawn (its wallet owes Dakota a card debt; close it if it must never spend again, or retry once the debt is paid).

7. Rename a card

PATCH /cards/{card_id} with nickname, up to 64 characters. A nickname can be replaced, but not removed.

8. Change a spend limit

PUT /cards/{card_id}/spend_limit with interval and amount in minor units. The new limit replaces the old one and applies from the next purchase.

9. Show the available balance

GET /wallets/{wallet_id}/balances. The card object carries total, held, outstanding, and available. Show available to the cardholder. A purchase can need slightly more than its own amount, so one for the entire available balance can be declined. Details: Card funding.

10. Track purchases

  1. Listen for card_transaction.created (an approved or declined authorization) and card_transaction.updated (every later change to the same purchase). Switch on status.
  2. To backfill or reconcile, GET /card_transactions, filtered by customer_id, card_id, or cardholder_id, and GET /card_transactions/{card_transaction_id}.
Details: Card funding and Cards webhooks.

11. Find cards and cardholders

external_id filters are exact and case-sensitive, and can match more than one record.

12. Report a dispute

POST /card_dispute_reports with the card_id, your client_reference, a reason, when the cardholder told you (consumer_notified_client_at), and when you reported it to Dakota (client_forwarded_at). The call records the report; Dakota reviews it and files the dispute with the network. Details: Disputes.

Offboarding

13. Remove a cardholder

  1. Close each of the cardholder’s cards with PATCH /cards/{card_id} and status: "closed". Do this first: the delete is refused while any of their cards is not closed, including a frozen one, and the error says how many are still open. Retrying the delete does not help until they are closed.
  2. DELETE /cardholders/{cardholder_id}.
  3. Wait for cardholder.updated with status: "closed". The cardholder is no longer returned by the API.
To update a cardholder’s contact details instead, use PATCH /cardholders/{cardholder_id}.

Testing

14. Run a purchase in sandbox

  1. POST /sandbox/wallets/{wallet_id}/faucet to fund the wallet. Poll GET /sandbox/simulations/{simulation_id} until state_position is completed. If it reads failed, call the faucet again with a new idempotency key.
  2. POST /sandbox/cards/simulate/transaction to authorize a purchase. card_transaction.created fires. If the response has status: "pending", it has no card_transaction_id yet: poll GET /sandbox/simulations/{simulation_id} until it names one.
  3. POST /sandbox/cards/simulate/transaction/{card_transaction_id} with an action such as clear, void, or return. card_transaction.updated fires.
Details: Testing Cards.