Tài liệu API — CryptoTopCard API Thẻ Ảo

Xác thực

Khóa API & Xác thực

Tất cả yêu cầu API đều cần token Bearer. Tạo khóa API từ Bảng điều khiển → Cài đặt → Khóa API.

Bảo mật Khóa API

Không bao giờ để lộ khóa trong mã phía client. Sử dụng biến môi trường. Khóa có tiền tố sk_live_ là production, sk_test_ là sandbox.

request-headers

Authorization: Bearer sk_live_your_api_key_here
Content-Type: application/json
X-Idempotency-Key: optional-unique-key-for-safe-retries

Giới hạn Tốc độ

1,000

Yêu cầu / Phút

50

Tạo thẻ / Phút

10,000

Yêu cầu / Giờ

Mã Lỗi

error-response.json

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

200

Yêu cầu thành công

201

Tài nguyên đã tạo

400

Tham số yêu cầu không hợp lệ

401

Khóa API thiếu hoặc không hợp lệ

404

Không tìm thấy tài nguyên

429

Vượt quá giới hạn tốc độ

Thẻ

Quản lý Thẻ

Tạo, quản lý và kiểm soát thẻ ảo Visa & Mastercard. Mỗi thẻ được cô lập với số dư, giới hạn và vòng đời riêng.

POST /cards Phát hành thẻ ảo mới

Nội dung Yêu cầu

Tham số	Kiểu		Mô tả
bin_id	string	required	Mã định danh BIN (vd. `491653`). Dùng `GET /bins` để liệt kê BINs có sẵn.
amount	number	required	Số tiền nạp ban đầu bằng USD. Tối thiểu: $1.00, Tối đa: $5,000.00
label	string	optional	Nhãn tùy chỉnh cho thẻ (tối đa 64 ký tự)
spending_limit	number	optional	Giới hạn chi tiêu hàng tháng bằng USD. Mặc định: tối đa của BIN.
allowed_categories	string[]	optional	Danh mục MCC cho danh sách trắng (vd. `["advertising", "software"]`)
auto_freeze_at	number	optional	Tự động đóng băng khi số dư giảm xuống dưới mức này
metadata	object	optional	Cặp khóa-giá trị cho theo dõi nội bộ (tối đa 20 khóa)

Yêu cầu Mẫu

curl

curl -X POST https://api.cryptotopcard.com/v1/cards \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bin_id": "491653",
    "amount": 500,
    "label": "Meta Ads Campaign #12",
    "spending_limit": 2000,
    "allowed_categories": ["advertising"],
    "metadata": {"campaign": "spring_2026"}
  }'

Phản hồi 201 Created

response.json

{
  "id": "card_8xK2m9Lp4q",
  "bin_id": "491653",
  "network": "visa",
  "last4": "2039",
  "status": "active",
  "balance": 500.00,
  "spending_limit": 2000.00,
  "label": "Meta Ads Campaign #12",
  "allowed_categories": ["advertising"],
  "auto_freeze_at": null,
  "metadata": { "campaign": "spring_2026" },
  "created_at": "2026-04-15T12:00:00Z",
  "expires_at": "2029-04-15T23:59:59Z"
}

GET /cards Liệt kê tất cả thẻ với bộ lọc và phân trang

Tham số Truy vấn

Tham số	Kiểu		Mô tả
status	string	optional	`active`, `frozen`, `terminated`
bin_id	string	optional	Lọc theo BIN
label	string	optional	Tìm theo nhãn (khớp một phần)
sort	string	optional	`created_at`, `balance`, `last_used`. Mặc định: `created_at`
order	string	optional	`asc` hoặc `desc`. Mặc định: `desc`
page	integer	optional	Số trang. Mặc định: `1`
per_page	integer	optional	Mục trên mỗi trang (1-100). Mặc định: `25`

Phản hồi 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} Lấy tóm tắt thẻ (không có dữ liệu nhạy cảm)

Trả về thông tin thẻ không có dữ liệu nhạy cảm. Dùng /cards/{card_id}/details để lấy PAN đầy đủ và CVV.

Phản hồi 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 Lấy PAN đầy đủ, CVV và ngày hết hạn

Endpoint Nhạy cảm

Trả về PAN đầy đủ, CVV và ngày hết hạn. Dữ liệu PCI nhạy cảm — không bao giờ ghi log hoặc lưu trữ không mã hóa. Giới hạn 30 yêu cầu/phút.

Phản hồi 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} Cập nhật cài đặt thẻ

Nội dung Yêu cầu

Tham số	Kiểu		Mô tả
label	string	optional	Cập nhật nhãn thẻ
spending_limit	number	optional	Cập nhật giới hạn chi tiêu hàng tháng
allowed_categories	string[]	optional	Cập nhật danh mục MCC được phép
auto_freeze_at	number	optional	Đặt ngưỡng đóng băng tự động. `0` để tắt.
metadata	object	optional	Hợp nhất với metadata hiện có

Phản hồi 200 OK

Trả về đối tượng thẻ đã cập nhật.

POST /cards/{card_id}/freeze Tạm đình chỉ thẻ

Tạm dừng tất cả giao dịch. Số dư được bảo toàn. Thẻ có thể được mở đóng băng sau.

Phản hồi 200 OK

response.json

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

POST /cards/{card_id}/unfreeze Kích hoạt lại thẻ đã đóng băng

Kích hoạt lại giao dịch trên thẻ đã đóng băng. Trả về đối tượng thẻ với status: "active".

DELETE /cards/{card_id} Hủy thẻ vĩnh viễn

Hành động Không thể Hoàn tác

Hủy thẻ là vĩnh viễn. Số dư còn lại được trả về ví của bạn ngay lập tức.

Phản hồi 200 OK

response.json

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

Nạp tiền

Nạp tiền Thẻ

Thêm hoặc rút tiền từ các thẻ riêng lẻ. Tiền lấy từ số dư ví của bạn.

POST /cards/{card_id}/fund Thêm tiền vào thẻ

Nội dung Yêu cầu

Tham số	Kiểu		Mô tả
amount	number	required	Số tiền USD cần thêm. Tối thiểu: $1.00, Tối đa: $5,000.00

Phản hồi 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 Rút tiền về ví

Nội dung Yêu cầu

Tham số	Kiểu		Mô tả
amount	number	required	Số tiền USD rút từ thẻ về ví

Phản hồi 200 OK

Trả về số dư thẻ và ví đã cập nhật.

Giao dịch

Lịch sử Giao dịch

Xem tất cả giao dịch trên các thẻ. Bao gồm ủy quyền, thanh toán, hoàn tiền và từ chối.

GET /transactions Liệt kê tất cả giao dịch với bộ lọc

Tham số Truy vấn

Tham số	Kiểu		Mô tả
card_id	string	optional	Lọc theo thẻ
type	string	optional	`authorization`, `settlement`, `refund`, `decline`
from	string	optional	Ngày bắt đầu (ISO 8601)
to	string	optional	Ngày kết thúc (ISO 8601)
merchant	string	optional	Tìm theo tên merchant (khớp một phần)
min_amount	number	optional	Số tiền giao dịch tối thiểu
max_amount	number	optional	Số tiền giao dịch tối đa
page	integer	optional	Số trang. Mặc định: `1`
per_page	integer	optional	Mục trên mỗi trang (1-100). Mặc định: `50`

Phản hồi 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} Lấy chi tiết giao dịch đầy đủ

Trả về đối tượng giao dịch đầy đủ bao gồm chi tiết merchant, mã MCC, trạng thái 3DS và dòng thời gian ủy quyền.

Ví

Ví & Nạp tiền

Quản lý ví tài khoản. Nạp crypto, kiểm tra số dư và theo dõi các khoản nạp đến.

GET /wallet/balance Lấy số dư và thống kê ví

Phản hồi 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 Lấy địa chỉ nạp crypto

Tham số Truy vấn

Tham số	Kiểu		Mô tả
currency	string	optional	`btc`, `eth`, `sol`, `usdt`. Bỏ qua để lấy tất cả.

Phản hồi 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 Liệt kê lịch sử nạp tiền

Tham số Truy vấn

Tham số	Kiểu		Mô tả
status	string	optional	`pending`, `confirmed`, `expired`
currency	string	optional	Lọc theo tiền điện tử

Phản hồi 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

Chọn BIN

Liệt kê các dải BIN có sẵn với khả năng, giới hạn và tỷ lệ chấp nhận.

GET /bins Liệt kê tất cả BINs có sẵn

Phản hồi 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

Xác thực 3D Secure

Truy xuất thử thách 3DS và mã OTP. Tất cả thẻ được đăng ký 3DS 2.0 tự động.

GET /3ds Liệt kê thử thách 3DS đang chờ

Tham số Truy vấn

Tham số	Kiểu		Mô tả
card_id	string	optional	Lọc theo thẻ
status	string	optional	`pending`, `completed`, `expired`

Phản hồi 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} Lấy OTP 3DS cụ thể

Trả về đối tượng thử thách 3DS đầy đủ bao gồm mã OTP. OTP hết hạn sau 5 phút.

Webhooks

Webhooks & Sự kiện

Nhận thông báo thời gian thực khi sự kiện xảy ra. Payload được ký bằng HMAC-SHA256.

Sự kiện Có sẵn

card.createdThẻ mới được phát hành

card.frozenThẻ đã bị đóng băng

card.unfrozenThẻ đã được mở đóng băng

card.terminatedThẻ đã bị hủy

card.fundedĐã thêm tiền vào thẻ

transaction.authorizedGiao dịch được ủy quyền

transaction.settledGiao dịch đã thanh toán

transaction.declinedGiao dịch bị từ chối

transaction.refundedHoàn tiền đã xử lý

3ds.challengeYêu cầu xác minh 3DS

deposit.pendingPhát hiện nạp crypto

deposit.confirmedNạp crypto đã xác nhận

Xác minh Chữ ký

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 Đăng ký endpoint webhook

Nội dung Yêu cầu

Tham số	Kiểu		Mô tả
url	string	required	URL endpoint HTTPS để nhận sự kiện
events	string[]	required	Loại sự kiện để đăng ký. Dùng `["*"]` cho tất cả.
secret	string	optional	Khóa ký tùy chỉnh. Tự động tạo nếu bỏ qua.

Phản hồi 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 Liệt kê webhooks đã đăng ký

Trả về mảng tất cả endpoint webhook đã đăng ký với đăng ký sự kiện và trạng thái.

DELETE /webhooks/{webhook_id} Xóa webhook

Xóa vĩnh viễn webhook. Không có sự kiện nào sẽ được gửi đến endpoint này nữa.

SDKs

SDKs & Thư viện

Thư viện client chính thức cho stack của bạn. Tất cả SDK hỗ trợ môi trường production và sandbox.

Python

pip install cryptotopcard

Node.js

npm i cryptotopcard

Go

go get cryptotopcard

Bắt đầu Nhanh — Python

quickstart.py

from cryptotopcard import Client

client = Client("sk_live_your_api_key")

# Tạo thẻ
card = client.cards.create(
    bin_id="491653",
    amount=500,
    label="Ad Spend"
)
print(card.id, card.last4)

# Lấy chi tiết thẻ đầy đủ (PAN, CVV)
details = client.cards.details(card.id)
print(details.pan, details.cvv)

# Nạp tiền thẻ
client.cards.fund(card.id, amount=200)

# Liệt kê giao dịch
txns = client.transactions.list(card_id=card.id)
for t in txns.data:
    print(t.merchant.name, t.amount)

Bắt đầu Nhanh — Node.js

quickstart.js

const { CryptoTopCard } = require('cryptotopcard');

const client = new CryptoTopCard('sk_live_your_api_key');

// Tạo thẻ
const card = await client.cards.create({
  binId: '491653',
  amount: 500,
  label: 'Ad Spend',
});

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

// Thiết lập webhooks
await client.webhooks.create({
  url: 'https://yourapp.com/hooks',
  events: ['transaction.authorized', '3ds.challenge'],
});

API Tham khảo

Khóa API & Xác thực

Bảo mật Khóa API

Quản lý Thẻ

Endpoint Nhạy cảm

Hành động Không thể Hoàn tác

Nạp tiền Thẻ

Lịch sử Giao dịch

Ví & Nạp tiền

Chọn BIN

Xác thực 3D Secure

Webhooks & Sự kiện

SDKs & Thư viện

Python

Node.js

Go

Chào mừng trở lại

Tạo tài khoản

Tài khoản đã được tạo