Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.seismic-cards.systems/llms.txt

Use this file to discover all available pages before exploring further.

The Seismic Cards API is a PCI-compliant card issuance platform that lets you embed virtual Visa and Mastercard cards directly into your product. From a single API integration, you can provision user accounts, run identity verification, create cardholders, fund budgets, issue cards, and track authorizations in real time — without ever touching raw card data.

​
What you can do

CapabilityDescription
Sub-account provisioningCreate one Seismic sub-account per end user. Each sub-account is the legal envelope that owns the user’s cardholder, budget, and cards.
KYC / KYBSubmit identity verification via supported KYC providers or Seismic’s hosted flow. KYC must pass before a card can be issued.
Cardholder managementCreate one persistent cardholder profile per user. Update phone, email, and name at any time.
BudgetsPer-user funding pools that back cards. Top up and withdraw on demand.
Virtual card issuanceIssue Visa or Mastercard virtual cards (VIRTUAL_CARD). Up to N cards per user (configurable per program).
Card lifecycleFreeze, unfreeze, rename, and delete cards.
Spending controlsSet per-card velocity limits — per transaction, daily, weekly, monthly, quarterly, yearly, or lifetime.
PCI display widgetShow full PAN, CVV, and expiry in your iOS, Android, or web app inside an iframe. Your servers never touch raw card data.
Real-time webhooksReceive card authorizations, KYC status updates, and cardholder events. All payloads are HMAC-SHA256 signed.
TransactionsList card authorizations and settled transactions with merchant name, MCC, amount, and status.

​
Architecture overview

Seismic’s card platform uses a two-tier hierarchy. Your partner account sits at the top; every end user gets their own sub-account underneath it. 
┌─────────────────────────────────────────────────────────────────┐
│                  YOUR PARTNER ACCOUNT (you)                     │
│  parentAccountId — held by you, the program operator            │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │   USER SUB-ACCOUNT (one per end user)                   │    │
│  │   accountId — provisioned via /v1/accounts/register     │    │
│  │                                                         │    │
│  │   ┌──────────────┐  ┌──────────────┐                    │    │
│  │   │  Cardholder  │  │    Budget    │                    │    │
│  │   │  (1 per user)│  │  (USD pool)  │                    │    │
│  │   └──────┬───────┘  └──────┬───────┘                    │    │
│  │          └──────┬──────────┘                            │    │
│  │                 ▼                                       │    │
│  │           ┌────────────┐                                │    │
│  │           │ Virtual    │   1..N per user                │    │
│  │           │ Card(s)    │                                │    │
│  │           └────────────┘                                │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
  • Your partner account is created by Seismic during onboarding. You receive a clientId, clientSecret, parentAccountId, and a merchantId.
  • One sub-account per end user. Every cardholder, budget, and card lives under exactly one user sub-account.
  • One cardholder per user. All of a user’s cards share one KYC’d cardholder identity.
  • One or more budgets per user. Cards spend from the budget they’re attached to. The budget must be funded before authorizations can succeed.
  • Many cards per user. Each card is VIRTUAL_CARD by default and inherits the cardholder’s identity and the budget’s balance.

​
Card issuance flow

Every card you issue follows this six-step path. Steps 1–3 happen once per user. Steps 4–6 happen every time you issue a new card for that user. 
   ┌─────────────────────────┐
1. │  Authenticate           │  POST /v1/oauth/access-token
   │  → access token (24h)   │
   └────────────┬────────────┘
                │
                ▼
   ┌─────────────────────────┐
2. │  Create sub-account     │  POST /v1/accounts/register
   │  for the end user       │
   └────────────┬────────────┘
                │
                ▼
   ┌─────────────────────────┐
3. │  Submit KYC             │  POST /v1/accounts/{accountId}/kyc
   │  Wait for APPROVED      │  (webhook: KYC.UPDATED)
   │  Initialize account     │  POST /v1/accounts/{accountId}/init
   └────────────┬────────────┘
                │
                ▼
   ┌─────────────────────────┐
4. │  Resolve a BIN          │  GET  /v1/card/bins
   │  Create cardholder      │  POST /v1/cardholders         (once)
   │  Create budget          │  POST /v1/budgets             (once)
   └────────────┬────────────┘
                │
                ▼
   ┌─────────────────────────┐
5. │  Fund the budget        │  POST /v1/budgets/{id}/transfer-in
   └────────────┬────────────┘
                │
                ▼
   ┌─────────────────────────┐
6. │  Issue virtual card     │  POST /v1/budget-card
   │  → cardId, last 4, BIN  │
   └─────────────────────────┘
Once issued, a card is ACTIVE and ready for online purchases. Use the PCI widget to display full card details in your UI, and consume webhooks to track authorizations in real time. For a complete step-by-step walkthrough with copy-paste curl examples, see Issuing a Card.

​
Conventions

Understanding these conventions will help you read every endpoint’s documentation consistently. Format All requests and responses use application/json with UTF-8 encoding. Success responses always have this shape: 
{ "code": "000000", "message": "success", "data": { ... } }
Error responses always have this shape: 
{ "code": "40001", "message": "Invalid parameter" }
See Error Codes for the full list. Amounts All monetary amounts are USD strings with up to two decimal places — for example, "100.00" or "0.50". Timestamps All timestamps are Unix milliseconds (as strings) unless a field’s documentation notes otherwise. UUIDs All IDs are UUID v4. The referenceId field is your chosen idempotency key per resource — keep it unique per request. Idempotency Mutating endpoints (POST to create or transfer) require an Idempotency-Key header — a UUID v4 you generate. Sending the same key with the same body returns the same response, so it’s safe to retry on network errors.

​
Support

  • Sandbox dashboard: provided by your account manager during onboarding
  • Status page: status.seismic.systems
  • Email: support@seismic.systems
  • Production access: complete your sandbox integration, then request production credentials from your account manager