Nhà phát triển · REST API v1

Phát hành thẻ ngay từ code của bạn

Tạo, nạp tiền, đóng băng và hủy thẻ Visa, Mastercard ảo qua HTTPS. Yêu cầu dùng JSON, xác thực bằng khóa bí mật và trừ vào cùng số dư USDT mà bạn nạp bằng crypto.

URL gốchttps://usdtcryptocard.com/api/v1
Xác thực
Bearer sk_live_…
Định dạng
JSON qua HTTPS
Endpoint
15
Webhook
Ký bằng HMAC-SHA256

Giới thiệu

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

Số tiền tính bằng đô la Mỹ với hai chữ số thập phân. Thời gian theo chuẩn ISO 8601, múi giờ UTC. Các endpoint danh sách được phân trang bằng page và per_page.

  1. Tạo khóaMở mục Truy cập API trong bảng điều khiển và tạo một khóa.
  2. Yêu cầu bật APIXác nhận email, nạp tiền lần đầu, rồi nhờ bộ phận hỗ trợ bật API.
  3. Gọi thửKiểm tra số dư bằng yêu cầu bên phải, rồi phát hành thẻ đầu tiên.
Lệnh gọi đầu tiên
Yêu cầu
curl https://usdtcryptocard.com/api/v1/wallet/balance \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "balance": 1312.5,
  "currency": "USDT",
  "pending_deposits": 500,
  "cards_active": 8,
  "cards_total_balance": 2450
}

Xác thực

Gửi khóa bí mật dưới dạng Bearer token trong header Authorization của mọi yêu cầu. Khóa bắt đầu bằng sk_live_ và được tạo trong bảng điều khiển, tại mục Truy cập API.

Chỉ giữ khóa trên máy chủ

Ai có khóa đều có thể chuyển tiền trong tài khoản của bạn. Hãy nạp khóa từ biến môi trường và đừng bao giờ đặt nó trong code trình duyệt hay ứng dụng di động.

Trước yêu cầu đầu tiên

Khóa mới sẽ trả về 403 cho đến khi tài khoản sẵn sàng. Bạn nhận 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 bộ phận hỗ trợ bật quyền truy cập API. Hãy nhắn cho chúng tôi để được bật.

Header
Yêu cầu
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
X-Idempotency-Key: 7c1e2f0a-retry-safe

Lỗi

Mọi phản hồi không phải 2xx đều kèm body JSON: một mã lỗi cố định để bạn rẽ nhánh xử lý, và một thông điệp dễ đọc cho con người.

200
Yêu cầu thành công
201
Tài nguyên đã tạo
400
Tham số không hợp lệ
401
Khóa API thiếu hoặc không hợp lệ
403
Khóa hợp lệ, nhưng tài khoản này chưa được bật quyền truy cập API
404
Không tìm thấy tài nguyên
429
Vượt quá giới hạn tốc độ
error.json
Phản hồi403
{
  "error": "api_not_enabled",
  "message": "Open a support ticket from your dashboard to enable API access."
}

Giới hạn tần suất

Giới hạn được tính theo từng khóa API. Vượt quá sẽ nhận 429: đợi một lát rồi thử lại với backoff.

Yêu cầu / Phút
1.000
Thẻ / Phút
50
Yêu cầu / Giờ
10.000
Thẻ

Quản Lý Thẻ

Mỗi thẻ có số dư, hạn mức và vòng đời riêng, nên chiến dịch, khách hàng hay gói đăng ký này không bao giờ ảnh hưởng đến cái khác.

POST/cards

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

Phát hành thẻ trên BIN bạn chọn và nạp tiền từ số dư ngay trong cùng một lệnh gọi.

Body Yêu Cầu

bin_idstringbắt buộc
Định danh BIN (vd. 491653). Sử dụng GET /bins để liệt kê BIN khả dụng.
amountnumberbắt buộc
Số tiền nạp ban đầu bằng USD, trừ từ số dư của bạn. Tối thiểu $50; phí phát hành $1 được tính thêm.
labelstringtùy chọn
Nhãn tùy chỉnh cho thẻ (tối đa 64 ký tự)
spending_limitnumbertùy chọn
Giới hạn chi tiêu hàng tháng bằng USD. Mặc định tối đa BIN.
allowed_categoriesstring[]tùy chọn
Các nhóm ngành hàng mà thẻ được phép dùng, ví dụ quảng cáo hoặc phần mềm. Mọi giao dịch khác sẽ bị từ chối.
auto_freeze_atnumbertùy chọn
Tự động đóng băng khi số dư xuống dưới mức này
metadataobjecttùy chọn
Cặp khóa-giá trị cho theo dõi nội bộ (tối đa 20 khóa)
POST /v1/cards
Yêu cầu
curl -X POST https://usdtcryptocard.com/api/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": "fall_2026"
    }
  }'
Phản hồi201
{
  "id": "card_8xK2m9Lp4q",
  "bin_id": "491653",
  "network": "visa",
  "last4": "2039",
  "status": "active",
  "balance": 500,
  "spending_limit": 2000,
  "label": "Meta Ads — Campaign 12",
  "allowed_categories": [
    "advertising"
  ],
  "auto_freeze_at": null,
  "metadata": {
    "campaign": "fall_2026"
  },
  "created_at": "2026-09-30T12:00:00Z",
  "expires_at": "2030-10-31"
}
GET/cards

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

Danh sách thẻ của bạn, mới nhất trước.

Tham Số Query

statusstringtùy chọn
Lọc theo trạng tháiactivefrozenterminated
bin_idstringtùy chọn
Lọc theo BIN
pageintegertùy chọn
Số trang. Mặc định: 1
per_pageintegertùy chọn
Mục mỗi trang (1-100). Mặc định: 25
GET /v1/cards
Yêu cầu
curl https://usdtcryptocard.com/api/v1/cards?status=active&per_page=25 \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "data": [
    {
      "id": "card_8xK2m9Lp4q",
      "bin_id": "491653",
      "network": "visa",
      "last4": "2039",
      "status": "active",
      "balance": 500,
      "spending_limit": 2000,
      "label": "Meta Ads — Campaign 12"
    }
  ],
  "page": 1,
  "per_page": 25,
  "total": 1
}
GET/cards/{card_id}

Lấy tóm tắt thẻ (không có dữ liệu nhạy cảm)

Thông tin thẻ, không kèm số thẻ và CVV. Dùng endpoint chi tiết khi bạn cần những thông tin đó.

Tham số đường dẫn

card_idstringbắt buộc
ID của thẻ, như được trả về khi bạn tạo thẻ.
GET /v1/cards/{card_id}
Yêu cầu
curl https://usdtcryptocard.com/api/v1/cards/card_8xK2m9Lp4q \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "id": "card_8xK2m9Lp4q",
  "bin_id": "491653",
  "network": "visa",
  "last4": "2039",
  "status": "active",
  "balance": 500,
  "spending_limit": 2000,
  "label": "Meta Ads — Campaign 12",
  "created_at": "2026-09-30T12:00:00Z"
}
GET/cards/{card_id}/details

Lấy PAN, CVV và hết hạn đầy đủ

Endpoint Nhạy Cảm

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

Tham số đường dẫn

card_idstringbắt buộc
ID của thẻ, như được trả về khi bạn tạo thẻ.
GET /v1/cards/{card_id}/details
Yêu cầu
curl https://usdtcryptocard.com/api/v1/cards/card_8xK2m9Lp4q/details \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "id": "card_8xK2m9Lp4q",
  "pan": "4916530000002039",
  "cvv": "123",
  "exp_month": 10,
  "exp_year": 2030
}
POST/cards/{card_id}/freeze

Tạm thời đình chỉ thẻ

Đình chỉ tất cả giao dịch. Số dư được bảo toàn. Thẻ có thể được mở khóa sau.

Tham số đường dẫn

card_idstringbắt buộc
ID của thẻ, như được trả về khi bạn tạo thẻ.
POST /v1/cards/{card_id}/freeze
Yêu cầu
curl -X POST https://usdtcryptocard.com/api/v1/cards/card_8xK2m9Lp4q/freeze \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "id": "card_8xK2m9Lp4q",
  "status": "frozen",
  "balance": 500
}
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".

Tham số đường dẫn

card_idstringbắt buộc
ID của thẻ, như được trả về khi bạn tạo thẻ.
POST /v1/cards/{card_id}/unfreeze
Yêu cầu
curl -X POST https://usdtcryptocard.com/api/v1/cards/card_8xK2m9Lp4q/unfreeze \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "id": "card_8xK2m9Lp4q",
  "status": "active",
  "balance": 500
}
DELETE/cards/{card_id}

Chấm dứt thẻ vĩnh viễn

Hành Động Không Thể Hoàn Tác

Chấm dứt 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.

Tham số đường dẫn

card_idstringbắt buộc
ID của thẻ, như được trả về khi bạn tạo thẻ.
DELETE /v1/cards/{card_id}
Yêu cầu
curl -X DELETE https://usdtcryptocard.com/api/v1/cards/card_8xK2m9Lp4q \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "id": "card_8xK2m9Lp4q",
  "status": "terminated",
  "returned_to_wallet": 500
}
Nạp Tiền

Nạp Tiền Thẻ

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

POST/cards/{card_id}/fund

Thêm tiền vào thẻ

Chuyển tiền từ số dư của bạn vào thẻ. Có thể chi tiêu ngay lập tức.

Tham số đường dẫn

card_idstringbắt buộc
ID của thẻ, như được trả về khi bạn tạo thẻ.

Body Yêu Cầu

amountnumberbắt buộc
Số tiền bằng USD chuyển từ số dư vào thẻ.
POST /v1/cards/{card_id}/fund
Yêu cầu
curl -X POST https://usdtcryptocard.com/api/v1/cards/card_8xK2m9Lp4q/fund \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 200
  }'
Phản hồi200
{
  "card_id": "card_8xK2m9Lp4q",
  "card_balance": 700,
  "wallet_balance": 612.5
}
POST/cards/{card_id}/withdraw

Rút tiền về ví

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

Tham số đường dẫn

card_idstringbắt buộc
ID của thẻ, như được trả về khi bạn tạo thẻ.
POST /v1/cards/{card_id}/withdraw
Yêu cầu
curl -X POST https://usdtcryptocard.com/api/v1/cards/card_8xK2m9Lp4q/withdraw \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "card_id": "card_8xK2m9Lp4q",
  "card_balance": 0,
  "wallet_balance": 1312.5
}
Giao Dịch

Lịch Sử Giao Dịch

Xem tất cả giao dịch trên thẻ của bạn. Bao gồm phê duyệt, 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

Ủy quyền, quyết toán, hoàn tiền và giao dịch bị từ chối trên tất cả thẻ của bạn, mới nhất trước.

Tham Số Query

card_idstringtùy chọn
Lọc theo thẻ
typestringtùy chọn
Chỉ trả về giao dịch thuộc loại này.authorizationsettlementrefunddecline
fromstringtùy chọn
Ngày bắt đầu (ISO 8601)
tostringtùy chọn
Ngày kết thúc (ISO 8601)
pageintegertùy chọn
Số trang. Mặc định: 1
GET /v1/transactions
Yêu cầu
curl https://usdtcryptocard.com/api/v1/transactions?card_id=card_8xK2m9Lp4q \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "data": [
    {
      "id": "txn_3fQ9w1Zk",
      "card_id": "card_8xK2m9Lp4q",
      "type": "settlement",
      "amount": 42.9,
      "currency": "USD",
      "fee": 0.3,
      "merchant": {
        "name": "SPOTIFY",
        "mcc": "4899"
      },
      "created_at": "2026-09-30T14:02:11Z"
    }
  ],
  "page": 1
}
Ví

Ví & Nạp Tiền

Quản lý ví tài khoản của bạ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í

Số dư của bạn, giữ bằng USDT, cùng số tiền đang nằm trên các thẻ.

GET /v1/wallet/balance
Yêu cầu
curl https://usdtcryptocard.com/api/v1/wallet/balance \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "balance": 1312.5,
  "currency": "USDT",
  "pending_deposits": 500,
  "cards_active": 8,
  "cards_total_balance": 2450
}
GET/wallet/deposit-address

Lấy địa chỉ nạp crypto

Địa chỉ để gửi crypto. Khoản nạp được chuyển đổi sang USDT khi mạng lưới xác nhận.

Tham Số Query

currencystringtùy chọn
Chỉ trả về địa chỉ của đồng coin này. Bỏ trống để nhận tất cả.btcethsolusdtbnbtrxpolltcavaxarb
GET /v1/wallet/deposit-address
Yêu cầu
curl https://usdtcryptocard.com/api/v1/wallet/deposit-address?currency=usdt \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "data": [
    {
      "currency": "usdt",
      "network": "ERC-20 (Ethereum)",
      "address": "0x9c4e…b71a"
    }
  ]
}
BINs

Lựa Chọn BIN

9 BIN bạn có thể phát hành, kèm mạng thẻ và khả năng hỗ trợ ví.

GET/bins

Liệt kê tất cả BIN khả dụng

Danh mục BIN, kèm mạng thẻ, loại thẻ và hỗ trợ Apple Pay / Google Pay.

GET /v1/bins
Yêu cầu
curl https://usdtcryptocard.com/api/v1/bins \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "data": [
    {
      "id": "471938",
      "network": "visa",
      "category": "ads",
      "3ds": true,
      "apple_pay": true,
      "google_pay": true
    },
    {
      "id": "553184",
      "network": "mastercard",
      "category": "ads",
      "3ds": true,
      "apple_pay": true,
      "google_pay": true
    }
  ],
  "total": 9
}
3D Secure

Xác Thực 3D Secure

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

GET/3ds

Liệt kê các thử thách 3DS đang chờ

Các yêu cầu xác thực 3D Secure đang chờ kèm mã dùng một lần, giúp bạn hoàn tất thanh toán mà không cần điện thoại.

GET /v1/3ds
Yêu cầu
curl https://usdtcryptocard.com/api/v1/3ds?status=pending \
  -H "Authorization: Bearer sk_live_..."
Phản hồi200
{
  "data": [
    {
      "id": "3ds_m4n5o6p7",
      "card_id": "card_8xK2m9Lp4q",
      "merchant": "SPOTIFY",
      "amount": 9.99,
      "otp": "847291",
      "status": "pending",
      "expires_at": "2026-09-30T15:05:00Z"
    }
  ]
}
Webhooks

Webhooks & Sự Kiện

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

Sự Kiện Khả Dụng

card.created
Thẻ mới đã được phát hành
card.frozen
Thẻ đã bị đóng băng
card.unfrozen
Thẻ đã được mở khóa
card.terminated
Thẻ đã bị chấm dứt
card.funded
Tiền đã được thêm vào thẻ
transaction.authorized
Giao dịch được phê duyệt
transaction.settled
Giao dịch được thanh toán
transaction.declined
Giao dịch bị từ chối
transaction.refunded
Hoàn tiền được xử lý
3ds.challenge
Yêu cầu xác minh 3DS
deposit.pending
Phát hiện nạp crypto
deposit.confirmed
Nạp crypto được xác nhận

Xác Minh Chữ Ký

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 cố định trước khi tin dữ liệu nhận được.

verify
Mã
# Tính lại chữ ký của một payload thô
echo -n "$RAW_BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"
POST/webhooks

Đăng ký endpoint webhook

Đăng ký một endpoint HTTPS và các sự kiện mà nó sẽ nhận.

Body Yêu Cầu

urlstringbắt buộc
URL HTTPS endpoint để nhận sự kiện
eventsstring[]bắt buộc
Tên các sự kiện muốn đăng ký. Dùng ["*"] để nhận tất cả.
secretstringtùy chọn
Bí mật ký tùy chỉnh. Tự động tạo nếu bỏ qua.
POST /v1/webhooks
Yêu cầu
curl -X POST https://usdtcryptocard.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/cards",
    "events": [
      "transaction.authorized",
      "3ds.challenge"
    ]
  }'
Phản hồi201
{
  "id": "wh_5tLr8QaZ",
  "url": "https://example.com/hooks/cards",
  "events": [
    "transaction.authorized",
    "3ds.challenge"
  ],
  "secret": "whsec_…",
  "created_at": "2026-09-30T12:00:00Z"
}
Tài liệu API phát hành thẻ ảo | USDT Crypto Card