API thẻ ảo: Cách tự động phát hành thẻ bằng code

API phát hành thẻ dùng để làm gì

Phát hành vài thẻ bằng tay thì không sao. Nhưng phát hành một thẻ cho mỗi khách hàng, chiến dịch hay nhà cung cấp mới, rồi giữ cho từng thẻ luôn đủ tiền, sẽ nhanh chóng trở nên lặp đi lặp lại. API phát hành thẻ biến những bước đó thành code:

• Tự động tạo thẻ cho từng đối tượng, ví dụ khi một khách hàng mới đăng ký trong CRM của bạn.
• Nạp thêm vào thẻ theo lịch hoặc khi số dư xuống thấp.
• Đóng băng thẻ ngay lập tức khi chạm ngân sách hoặc hợp đồng kết thúc.
• Đồng bộ giao dịch vào công cụ kế toán hoặc báo cáo.
• Phản hồi sự kiện theo thời gian thực qua webhook thay vì phải polling.

API làm đúng những gì bảng điều khiển làm, nhưng từ máy chủ của bạn. Mọi thẻ bạn phát hành và mọi khoản nạp vào thẻ đều được trả từ số dư tài khoản, số dư mà bạn nạp bằng crypto và luôn được giữ bằng USDT.

Cách được cấp quyền truy cập API thẻ ảo

Có ba bước:

1. Tạo khóa. Mở mục truy cập API trong bảng điều khiển và tạo một khóa. Khóa bắt đầu bằng sk_live_.
2. Yêu cầu kích hoạt. Xác nhận email và thực hiện khoản nạp đầu tiên, rồi nhờ bộ phận hỗ trợ (qua ticket trong bảng điều khiển) bật API cho tài khoản của bạn.
3. Gọi API. Kiểm tra số dư, rồi phát hành thẻ đầu tiên.

Cho đến khi tài khoản sẵn sàng, một khóa hợp lệ sẽ nhận phản hồi 403. Bạn sẽ thấy mã lỗi onboarding_incomplete cho đến khi xác nhận email và nạp tiền lần đầu, sau đó là api_not_enabled cho đến khi quyền truy cập API được bật.

Không có môi trường sandbox riêng và không có gói SDK chính thức. Bạn gọi REST API trực tiếp bằng bất kỳ HTTP client nào, giúp việc tích hợp đơn giản nhưng cũng có nghĩa mọi lệnh gọi đều là thật. Hãy thử nghiệm với số tiền nhỏ.

Cơ bản: base URL, xác thực và định dạng

• Base URL: https://usdtcryptocard.com/api/v1
• Xác thực: gửi khóa dưới dạng Bearer token trong header Authorization của mọi request.
• Định dạng: JSON qua HTTPS. Số tiền tính bằng đô la Mỹ với hai chữ số thập phân. Mốc thời gian theo chuẩn ISO 8601, múi giờ UTC.
• Phân trang: các endpoint danh sách nhận page và per_page.

Giữ khóa trên máy chủ. Bất kỳ ai có khóa đều có thể chuyển tiền trong tài khoản của bạn, vì vậy hãy nạp khóa từ biến môi trường và đừng bao giờ đưa nó vào code trình duyệt hay ứng dụng di động.

Lệnh gọi đầu tiên

Kiểm tra số dư là một request đầu tiên an toàn:

curl https://usdtcryptocard.com/api/v1/wallet/balance \
  -H "Authorization: Bearer sk_live_..."

Phản hồi cho thấy số dư USDT, các khoản nạp đang chờ và số tiền đang nằm trên các thẻ:

{
  "balance": 1312.5,
  "currency": "USDT",
  "pending_deposits": 500.0,
  "cards_active": 8,
  "cards_total_balance": 2450.0
}

Các endpoint

API có 15 endpoint thuộc sáu nhóm tài nguyên.

Tham số đầy đủ và phản hồi mẫu có trong tài liệu tham chiếu API.

Phát hành thẻ bằng code

Khi tạo thẻ, bạn chọn BIN và nạp tiền vào thẻ từ số dư trong cùng một request. Các trường gồm:

• bin_id (bắt buộc): BIN dùng để phát hành. Liệt kê các lựa chọn bằng GET /bins.
• amount (bắt buộc): số tiền nạp ban đầu bằng USD, lấy từ số dư. Tối thiểu $50, phí phát hành $1 được tính thêm.
• label: tên bạn tự đặt cho thẻ.
• spending_limit: hạn mức chi tiêu bằng USD.
• allowed_categories: các danh mục người bán mà thẻ được phép dùng, như quảng cáo hoặc phần mềm. Mọi giao dịch khác sẽ bị từ chối.
• auto_freeze_at: tự động đóng băng thẻ khi số dư xuống dưới mức này.
• metadata: các cặp khóa-giá trị để bạn tự theo dõi.

Đây là cùng request đó bằng Node.js:

const res = await fetch('https://usdtcryptocard.com/api/v1/cards', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.USDTCC_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    bin_id: '491653',
    amount: 500,
    label: 'Meta Ads - Campaign 12',
    spending_limit: 2000,
    allowed_categories: ['advertising'],
    metadata: { campaign: 'fall_2026' },
  }),
});
const card = await res.json();

Lệnh gọi thành công trả về 201 cùng đối tượng thẻ: id, BIN, mạng thẻ, bốn số cuối, trạng thái, số dư, cùng label và metadata của bạn. Bản tóm tắt cố ý không kèm số thẻ đầy đủ và CVV.

Lấy số thẻ một cách an toàn

GET /cards/{card_id}/details trả về số thẻ đầy đủ, CVV và ngày hết hạn. Hãy coi đây là dữ liệu nhạy cảm: đừng bao giờ ghi log phản hồi hay lưu nó mà không mã hóa, và chỉ lấy khi bạn thực sự cần đưa thông tin cho một người hoặc một trang thanh toán. Endpoint này có giới hạn tần suất chặt hơn các endpoint còn lại.

Nạp tiền, đóng băng và hủy thẻ

• Nạp thêm: POST /cards/{card_id}/fund với amount chuyển tiền từ số dư vào thẻ. Tiền dùng được ngay.
• Rút tiền về: POST /cards/{card_id}/withdraw trả số dư của thẻ về ví.
• Tạm dừng: POST /cards/{card_id}/freeze tạm ngưng mọi giao dịch nhưng vẫn giữ số dư. unfreeze kích hoạt lại thẻ.
• Hủy: DELETE /cards/{card_id} hủy thẻ vĩnh viễn và trả số dư còn lại về ví. Thao tác này không thể hoàn tác.

Phí thông thường áp dụng cho hoạt động qua API, giống hệt trên bảng điều khiển: $1 mỗi thẻ phát hành, $0,30 mỗi giao dịch được chấp thuận (giao dịch bị từ chối miễn phí), và nạp thêm vào thẻ từ số dư miễn phí. Khoản nạp dưới $300 chịu phí 2%; từ $300 trở lên không mất phí. Xem mục bảng giá.

Webhook

Thay vì polling, hãy đăng ký một endpoint HTTPS bằng POST /webhooks, liệt kê các sự kiện bạn muốn nhận (hoặc ["*"] để nhận tất cả). Các sự kiện có sẵn gồm:

• card.created, card.frozen, card.unfrozen, card.terminated, card.funded
• transaction.authorized, transaction.settled, transaction.declined, transaction.refunded
• 3ds.challenge
• deposit.pending, deposit.confirmed

Mỗi lần gửi đều được ký bằng HMAC-SHA256 với secret của endpoint, secret này được tạo sẵn cho bạn nếu bạn không cung cấp. Hãy tính lại chữ ký trên body request thô và so sánh theo thời gian hằng định trước khi tin tưởng payload:

import crypto from 'node:crypto';

export function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Chỉ parse JSON sau khi xác minh thành công, và viết handler theo kiểu idempotent phòng khi một sự kiện đến nhiều hơn một lần.

Lỗi và giới hạn tần suất

Mọi phản hồi không phải 2xx đều kèm body JSON chứa mã error ổn định để bạn rẽ nhánh xử lý và một message dễ đọc. Các mã trạng thái bạn sẽ gặp là 400 (tham số không hợp lệ), 401 (thiếu khóa hoặc khóa không hợp lệ), 403 (tài khoản chưa sẵn sàng hoặc API chưa được bật), 404 (không tìm thấy) và 429 (vượt giới hạn tần suất).

Giới hạn được tính theo từng khóa API:

Nếu nhận 429, hãy chờ và thử lại với cơ chế exponential backoff.

Mẹo thiết kế để tích hợp ổn định

• Lưu id của thẻ, không lưu số thẻ. Chỉ lấy thông tin chi tiết khi cần.
• Dùng metadata và label để liên kết thẻ với dữ liệu của bạn, như mã khách hàng hoặc chiến dịch.
• Ưu tiên webhook thay vì polling cho giao dịch và yêu cầu xác thực 3D Secure.
• Giữ một khoản dự phòng trên thẻ dùng cho các khoản phí định kỳ, hoặc dùng auto_freeze_at và fund để tự động quản lý số dư.
• Tính trước các giới hạn. Giới hạn theo gói tài khoản vẫn áp dụng: gói Virtual cho phép $5.000 mỗi giao dịch và $20.000 mỗi tháng, còn gói Platinum, được mở khóa bằng một lần nạp từ $300 trở lên, không giới hạn chi tiêu.

Nếu bạn quản lý thẻ cho một nhóm thay vì viết code, hãy xem thẻ ảo cho đội nhóm. Với nhu cầu tài khoản quảng cáo, hãy đọc thẻ ảo chạy quảng cáo. Sẵn sàng bắt đầu? Tạo tài khoản.

Câu hỏi thường gặp

API thẻ ảo là gì?

Đó là giao diện cho phép phần mềm tự động tạo và quản lý thẻ thanh toán. Với USDT Crypto Card, đó là REST API dùng JSON qua HTTPS, xác thực bằng khóa bí mật sk_live_.

Có sandbox hay SDK không?

Không. Không có môi trường sandbox và không có gói SDK chính thức. Bạn gọi REST API trực tiếp bằng bất kỳ HTTP client nào, và mọi lệnh gọi đều là thật, vì vậy hãy thử với số tiền nhỏ.

Vì sao khóa API mới của tôi trả về 403?

Tài khoản chưa sẵn sàng. onboarding_incomplete nghĩa là bạn vẫn cần xác nhận email và nạp tiền lần đầu. api_not_enabled nghĩa là bộ phận hỗ trợ vẫn chưa bật quyền truy cập API.

Webhook được bảo mật thế nào?

Mỗi lần gửi đều được ký bằng HMAC-SHA256 với secret của endpoint. Hãy tính lại chữ ký trên body thô và so sánh theo thời gian hằng định trước khi tin tưởng payload.

Thẻ tạo qua API có cùng mức phí với thẻ tạo trên bảng điều khiển không?

Có. Áp dụng cùng mức phí: $1 mỗi thẻ, $0,30 mỗi giao dịch được chấp thuận, nạp thêm vào thẻ từ số dư miễn phí, và phí nạp 2% với khoản dưới $300.