Документация API - API виртуальных карт CryptoCardy

Аутентификация

Аутентификация по seed

Каждый API-запрос требует уникальный seed. Передавайте его в каждом запросе через заголовок X-Seed.

Безопасность seed

Храните seed в секрете. Относитесь к нему как к API-ключу: не встраивайте его в client-side код и храните в переменных окружения или менеджере секретов.

request-headers

X-Seed: c4f4-6e88-036c-761c
Content-Type: application/json
X-Idempotency-Key: optional-unique-key-for-safe-retries

Лимиты запросов

1,000

Requests / Minute

50

Card Creates / Minute

10,000

Requests / Hour

Коды ошибок

error-response.json

{
  "error": "insufficient_funds",
  "message": "Your wallet balance is too low to fund this card.",
  "code": 400,
  "request_id": "req_7f8a9b2c3d4e"
}

200

Запрос выполнен успешно

201

Ресурс создан

400

Некорректные параметры запроса

401

Seed отсутствует или недействителен

404

Ресурс не найден

429

Превышен лимит запросов

Карты

Управление картами

Создавайте и управляйте виртуальными картами Visa и Mastercard. У каждой карты есть собственный баланс, лимиты и жизненный цикл.

GET / Generate a seed, card preview, and funding wallet

Card State

New cards are returned with card.state set to pending_top_up. Once the wallet is funded, the card can be activated and used for payments.

Query Parameters

Parameter	Type		Description
card	string	optional	Card network: `visa` or `mastercard`. If omitted, a network is chosen automatically.
asset	string	optional	Funding asset (wallet address will be selected accordingly). Examples: `BTC`, `ETH`, `USDT-ERC20`, `USDT-SOL`, `SOL`, `XMR`.

Example Request

curl

curl "https://cryptocardy.com/v1/api?card=visa&asset=BTC"

Response 200 OK

response.json

{
  "success": true,
  "request_id": "req_bb0ade3fea54",
  "seed": "a1b2-c3d4-e5f6-7890",
  "card": {
    "state": "pending_top_up",
    "network": "visa",
    "card_number": "4916 5301 2345 2039",
    "cvv_masked": "601",
    "expiry": "04/29"
  },
  "wallet": {
    "asset": "BTC",
    "address": "bc1qag7fuerpyndyxgllx90vsmpk2ruku0qjg5aq54"
  },
  "created_at": "2026-05-22T17:57:34+00:00"
}

GET /cards List all cards with filters & pagination

Query Parameters

Parameter	Type		Description
status	string	optional	`active`, `frozen`, `terminated`
bin_id	string	optional	Filter by BIN
label	string	optional	Search by label (partial match)
sort	string	optional	`created_at`, `balance`, `last_used`. Default: `created_at`
order	string	optional	`asc` or `desc`. Default: `desc`
page	integer	optional	Page number. Default: `1`
per_page	integer	optional	Items per page (1-100). Default: `25`

Response 200 OK

response.json

{
  "data": [
    {
      "id": "card_8xK2m9Lp4q",
      "bin_id": "491653",
      "network": "visa",
      "last4": "2039",
      "status": "active",
      "balance": 487.50,
      "label": "Meta Ads Campaign #12",
      "created_at": "2026-04-15T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}

GET /cards/{card_id} Get card summary (no sensitive data)

Returns card info without sensitive details. Use /cards/{card_id}/details for the full PAN & CVV.

Response 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "bin_id": "491653",
  "network": "visa",
  "last4": "2039",
  "status": "active",
  "balance": 487.50,
  "spending_limit": 2000.00,
  "total_spent": 12.50,
  "transaction_count": 3,
  "label": "Meta Ads Campaign #12",
  "metadata": { "campaign": "spring_2026" },
  "created_at": "2026-04-15T12:00:00Z",
  "expires_at": "2029-04-15T23:59:59Z",
  "last_used_at": "2026-04-15T14:32:00Z"
}

GET /cards/{card_id}/details Get full PAN, CVV & expiry

Sensitive Endpoint

Returns full card PAN, CVV, and expiry. PCI-sensitive — never log or store unencrypted. Rate limited to 30 req/min.

Response 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "pan": "4916531288472039",
  "cvv": "847",
  "exp_month": 4,
  "exp_year": 2029,
  "holder_name": "ANONYMOUS",
  "billing_address": {
    "line1": "123 Privacy Street",
    "city": "Wilmington",
    "state": "DE",
    "zip": "19801",
    "country": "US"
  }
}

PATCH /cards/{card_id} Update card settings

Request Body

Parameter	Type		Description
label	string	optional	Update card label
spending_limit	number	optional	Update monthly spending limit
allowed_categories	string[]	optional	Update allowed MCC categories
auto_freeze_at	number	optional	Set auto-freeze threshold. `0` to disable.
metadata	object	optional	Merge with existing metadata

Response 200 OK

Returns the updated card object.

POST /cards/{card_id}/freeze Temporarily suspend a card

Suspends all transactions. Balance is preserved. Card can be unfrozen later.

Response 200 OK

response.json

{ "id": "card_8xK2m9Lp4q", "status": "frozen", "frozen_at": "2026-04-15T15:00:00Z" }

POST /cards/{card_id}/unfreeze Re-enable a frozen card

Re-enables transactions on a frozen card. Returns the card object with status: "active".

DELETE /cards/{card_id} Permanently terminate a card

Irreversible Action

Terminating a card is permanent. Remaining balance is returned to your wallet instantly.

Response 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "status": "terminated",
  "refunded_amount": 487.50,
  "terminated_at": "2026-04-15T16:00:00Z"
}

Пополнение

Пополнение карт

Добавляйте или выводите средства с отдельных карт. Средства списываются с баланса кошелька.

POST /cards/{card_id}/fund Add funds to a card

Request Body

Parameter	Type		Description
amount	number	required	Amount in USD to add. Min: $1.00, Max: $5,000.00

Response 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "previous_balance": 487.50,
  "funded_amount": 200.00,
  "new_balance": 687.50,
  "wallet_balance": 1312.50
}

POST /cards/{card_id}/withdraw Withdraw funds back to wallet

Request Body

Parameter	Type		Description
amount	number	required	Amount in USD to withdraw from the card back to wallet

Response 200 OK

Returns updated card and wallet balances.

Транзакции

История транзакций

Просматривайте все транзакции по своим картам, включая авторизации, списания, возвраты и отклонения.

GET /transactions List all transactions with filters

Query Parameters

Parameter	Type		Description
card_id	string	optional	Filter by card
type	string	optional	`authorization`, `settlement`, `refund`, `decline`
from	string	optional	Start date (ISO 8601)
to	string	optional	End date (ISO 8601)
merchant	string	optional	Search by merchant name (partial match)
min_amount	number	optional	Minimum transaction amount
max_amount	number	optional	Maximum transaction amount
page	integer	optional	Page number. Default: `1`
per_page	integer	optional	Items per page (1-100). Default: `50`

Response 200 OK

response.json

{
  "data": [
    {
      "id": "txn_a1b2c3d4",
      "card_id": "card_8xK2m9Lp4q",
      "type": "settlement",
      "amount": -12.50,
      "currency": "USD",
      "merchant": {
        "name": "FACEBK ADS",
        "category": "advertising",
        "mcc": "7311",
        "country": "US"
      },
      "balance_after": 487.50,
      "created_at": "2026-04-15T14:32:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 50, "total": 328 }
}

GET /transactions/{txn_id} Get full transaction details

Returns the full transaction object including merchant details, MCC code, 3DS status, and authorization timeline.

Wallet

Wallet i depozity

Manage your account wallet. Deposit crypto, check balances, and track incoming deposits.

GET /wallet/balance Get wallet balance & stats

Response 200 OK

response.json

{
  "balance": 1312.50,
  "currency": "USD",
  "pending_deposits": 500.00,
  "total_deposited": 15000.00,
  "total_spent": 13687.50,
  "cards_active": 8,
  "cards_total_balance": 2450.00
}

GET /wallet/deposit-address Get crypto deposit addresses

Query Parameters

Parameter	Type		Description
currency	string	optional	`btc`, `eth`, `sol`, `usdt`. Omit to get all.

Response 200 OK

response.json

{
  "addresses": {
    "btc": "bc1qxy2kgdygjrsqtzq2n0yrf...",
    "eth": "0x742d35Cc6634C0532925a3b...",
    "sol": "7xKXtg2CW87d97TXJSDpbD5j...",
    "usdt": "0x742d35Cc6634C0532925a3b..."
  },
  "networks": {
    "btc": "bitcoin",
    "eth": "ethereum",
    "sol": "solana",
    "usdt": "erc-20"
  },
  "min_deposit": {
    "btc": "0.0001",
    "eth": "0.005",
    "sol": "0.1",
    "usdt": "5.00"
  }
}

GET /wallet/deposits List deposit history

Query Parameters

Parameter	Type		Description
status	string	optional	`pending`, `confirmed`, `expired`
currency	string	optional	Filter by crypto currency

Response 200 OK

response.json

{
  "data": [
    {
      "id": "dep_x9y8z7w6",
      "currency": "btc",
      "amount_crypto": "0.0075",
      "amount_usd": 500.00,
      "fee_usd": 10.00,
      "credited_usd": 490.00,
      "status": "confirmed",
      "tx_hash": "3a1b2c3d4e5f...",
      "confirmations": 6,
      "created_at": "2026-04-15T10:00:00Z",
      "confirmed_at": "2026-04-15T10:42:00Z"
    }
  ]
}

BINs

Vybor BIN

List available BIN ranges with their capabilities, limits, and acceptance rates.

GET /bins List all available BINs

Response 200 OK

response.json

{
  "data": [
    {
      "id": "491653",
      "network": "visa",
      "type": "advertising",
      "issuer_country": "US",
      "3ds": true,
      "apple_pay": true,
      "google_pay": true,
      "max_transaction": 5000.00,
      "max_monthly": 50000.00,
      "acceptance_rate": 97.2,
      "best_for": ["meta_ads", "google_ads", "tiktok_ads"]
    },
    {
      "id": "531993",
      "network": "mastercard",
      "type": "everyday",
      "issuer_country": "US",
      "3ds": true,
      "apple_pay": true,
      "google_pay": true,
      "max_transaction": 1000.00,
      "max_monthly": 10000.00,
      "acceptance_rate": 95.8,
      "best_for": ["subscriptions", "saas", "shopping"]
    }
  ]
}

3D Secure

Retrieve 3DS challenges and OTP codes. All cards are enrolled in 3DS 2.0 automatically.

GET /3ds List pending 3DS challenges

Query Parameters

Parameter	Type		Description
card_id	string	optional	Filter by card
status	string	optional	`pending`, `completed`, `expired`

Response 200 OK

response.json

{
  "data": [
    {
      "id": "3ds_m4n5o6p7",
      "card_id": "card_8xK2m9Lp4q",
      "merchant": "SPOTIFY",
      "amount": 9.99,
      "otp": "847291",
      "status": "pending",
      "expires_at": "2026-04-15T15:05:00Z",
      "created_at": "2026-04-15T15:00:00Z"
    }
  ]
}

GET /3ds/{challenge_id} Get a specific 3DS OTP

Returns the full 3DS challenge object including the OTP code. OTPs expire after 5 minutes.

Webhooks

Вебхуки и события

Receive real-time notifications when events occur. Payloads are signed with HMAC-SHA256.

Available Events

card.createdA new card was issued

card.frozenA card was frozen

card.unfrozenA card was unfrozen

card.terminatedA card was terminated

card.fundedFunds added to a card

transaction.authorizedTransaction authorized

transaction.settledTransaction settled

transaction.declinedTransaction declined

transaction.refundedRefund processed

3ds.challenge3DS verification required

deposit.pendingCrypto deposit detected

deposit.confirmedCrypto deposit confirmed

Signature Verification

verify-webhook.py

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

POST /webhooks Register a webhook endpoint

Request Body

Parameter	Type		Description
url	string	required	HTTPS endpoint URL to receive events
events	string[]	required	Event types to subscribe. Use `["*"]` for all.
secret	string	optional	Custom signing secret. Auto-generated if omitted.

Response 201 Created

response.json

{
  "id": "wh_r5s6t7u8",
  "url": "https://yourapp.com/webhooks/ctc",
  "events": ["transaction.authorized", "transaction.declined"],
  "secret": "whsec_a1b2c3d4e5f6...",
  "active": true,
  "created_at": "2026-04-15T12:00:00Z"
}

GET /webhooks List registered webhooks

Returns array of all registered webhook endpoints with their event subscriptions and status.

DELETE /webhooks/{webhook_id} Delete a webhook

Permanently removes the webhook. No further events will be delivered to this endpoint.

SDKs

SDK i biblioteki

Official client libraries for your stack. All SDKs support live and sandbox environments.

Python

pip install CryptoCardy

Node.js

npm i CryptoCardy

Go

go get CryptoCardy

Quick Start — Python

quickstart.py

from CryptoCardy import Client

client = Client("c4f4-6e88-036c-761c")

# Create a card
card = client.cards.create(
    bin_id="491653",
    amount=500,
    label="Ad Spend"
)
print(card.id, card.last4)

# Get full card details (PAN, CVV)
details = client.cards.details(card.id)
print(details.pan, details.cvv)

# Fund the card
client.cards.fund(card.id, amount=200)

# List transactions
txns = client.transactions.list(card_id=card.id)
for t in txns.data:
    print(t.merchant.name, t.amount)

Quick Start — Node.js

quickstart.js

const { CryptoCardy } = require('CryptoCardy');

const client = new CryptoCardy('c4f4-6e88-036c-761c');

// Create a card
const card = await client.cards.create({
  binId: '491653',
  amount: 500,
  label: 'Ad Spend',
});

// Get 3DS OTPs
const challenges = await client.threeds.list({
  cardId: card.id,
  status: 'pending',
});

// Set up webhooks
await client.webhooks.create({
  url: 'https://yourapp.com/hooks',
  events: ['transaction.authorized', '3ds.challenge'],
});

Справочник API

Аутентификация по seed

Безопасность seed

Управление картами

Card State

Sensitive Endpoint

Irreversible Action

Пополнение карт

История транзакций

Wallet i depozity

Vybor BIN

3D Secure

Вебхуки и события

SDK i biblioteki

Python

Node.js

Go

Welcome back

Create Account

Account Created

Two-Factor Authentication