Tai lieu API - API the ao CryptoCardy

Authentication

Xac thuc bang seed

Moi yeu cau API deu can seed duy nhat cua ban. Gui no trong moi request bang header X-Seed.

Bao mat seed

Hay giu seed o che do rieng tu. Xem no nhu API key: khong hardcode vao client-side code va luu trong environment variables hoac secrets manager an toan.

request-headers

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

Rate Limits

1,000

Requests / Minute

50

Card Creates / Minute

10,000

Requests / Hour

Error Codes

error-response.json

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

200

Request succeeded

201

Resource created

400

Invalid request parameters

401

Missing or invalid seed

404

Resource not found

429

Rate limit exceeded

Cards

Quan ly the

Tao, quan ly va kiem soat the ao Visa va Mastercard. Moi the co so du, gioi han va vong doi rieng.

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"
}

Funding

Nap tien cho the

Them hoac rut tien tu tung the rieng. Tien duoc lay tu so du wallet cua ban.

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.

Transactions

Lich su giao dich

View all transactions across your cards. Includes authorizations, settlements, refunds, and declines.

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 va nap tien

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

Chon 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

Xac thuc 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

Webhook va su kien

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

SDKs va thu vien

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 Reference

Xac thuc bang seed

Bao mat seed

Quan ly the

Card State

Sensitive Endpoint

Irreversible Action

Nap tien cho the

Lich su giao dich

Wallet va nap tien

Chon BIN

Xac thuc 3D Secure

Webhook va su kien

SDKs va thu vien

Python

Node.js

Go

Welcome back

Create Account

Account Created

Two-Factor Authentication