Getting started
Core API basics
Card issuing
Navigate docsW PreviousS Next
Guide

Quickstart

Create the core resources using safe demo identifiers and idempotent writes.

Local start

Start the local API, worker and frontend using the commands registered in docs/references/20-commands.md. Do not infer extra CLIs or provider sandboxes unless those tools are installed and configured.

Integration sequence

Create customers, cardholders and cards through the public contract. Merchant and card program bootstrap remains controlled internally for the MVP.

  • POST /v1/customers
  • POST /v1/cardholders
  • POST /v1/cards
  • PATCH /v1/cards/{card_id}/controls
  • GET /v1/ledger/balances
  • GET /v1/webhook-deliveries

Example request

Use environment variables or a secret manager for API keys; do not paste stored secrets into docs, tickets or screenshots.

bash
curl http://localhost:8080/v1/cards \
  -H "X-API-Key: $YOUR_AICARD_API_KEY" \
  -H "Idempotency-Key: idem_2026_05_28_001" \
  -H "Content-Type: application/json" \
  -d '{"cardholder_id":"cardholder_demo","type":"virtual"}'

Expected fail-closed branch

Card creation can return card_issuance_unavailable or provider_required until ledger reserve, runtime provider config, persistent store and capability evidence are ready. Treat that as the correct local safety branch, not as proof of live issuing.