Sanal Kart API'si: Kart Çıkarmayı Kodla Nasıl Otomatikleştirirsiniz?

Kart çıkarma API'si ne işe yarar?

Birkaç kartı elle çıkarmak sorun değildir. Ancak her yeni müşteri, kampanya veya tedarikçi için kart çıkarmak ve her birinin bakiyesini sürdürmek hızla tekrara dönüşür. Kart çıkarma API'si bu adımları koda çevirir:

• Her varlık için otomatik kart oluşturun, örneğin CRM'inize yeni bir müşteri kaydolduğunda.
• Kartlara bir takvime göre ya da bakiyeleri düştüğünde yükleme yapın.
• Bir bütçeye ulaşıldığında veya bir sözleşme bittiğinde kartları anında dondurun.
• İşlemleri muhasebe veya raporlama araçlarınıza senkronize edin.
• Olaylara sorgulama (polling) yapmak yerine webhook'larla gerçek zamanlı tepki verin.

API, panelin yaptığını sunucunuzdan yapar. Çıkardığınız her kart ve yaptığınız her yükleme, kripto yatırmalarıyla beslediğiniz ve her zaman USDT olarak tutulan hesap bakiyenizden ödenir.

Sanal kart API'sine erişim

Erişim üç adımda sağlanır:

1. Anahtar oluşturun. Panelinizde API erişimini açın ve bir anahtar oluşturun. Anahtarlar sk_live_ ile başlar.
2. Erişimi açtırın. E-postanızı onaylayın ve ilk yatırmanızı yapın, ardından destekten (paneldeki bir destek talebi üzerinden) hesabınız için API'yi etkinleştirmesini isteyin.
3. Bir çağrı yapın. Bakiyenizi kontrol edin, ardından ilk kartınızı çıkarın.

Hesabınız hazır olana kadar geçerli bir anahtar 403 yanıtı alır. E-postanız onaylanıp ilk yatırmanızı yapana kadar onboarding_incomplete hata kodunu, ardından API erişimi açılana kadar api_not_enabled kodunu görürsünüz.

Ayrı bir sandbox ortamı ve resmi SDK paketleri yoktur. REST API'yi herhangi bir HTTP istemcisiyle doğrudan çağırırsınız; bu entegrasyonu basit tutar ama her çağrının canlı olduğu anlamına gelir. Küçük tutarlarla test edin.

Temeller: base URL, kimlik doğrulama ve format

• Base URL: https://usdtcryptocard.com/api/v1
• Kimlik doğrulama: anahtarınızı her isteğin Authorization başlığında Bearer token olarak gönderin.
• Format: HTTPS üzerinden JSON. Tutarlar iki ondalık basamaklı ABD dolarıdır. Zaman damgaları UTC'de ISO 8601'dir.
• Sayfalama: liste uç noktaları page ve per_page alır.

Anahtarı sunucunuzda tutun. Ona sahip olan herkes hesabınızda para hareket ettirebilir; bu yüzden onu bir ortam değişkeninden yükleyin ve asla tarayıcı veya mobil kodda dağıtmayın.

İlk çağrınız

Bakiyenizi kontrol etmek güvenli bir ilk istektir:

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

Yanıt; USDT bakiyenizi, bekleyen yatırmaları ve kartlarınızda duran tutarı gösterir:

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

Uç noktalar

API'de altı kaynak altında 15 uç nokta bulunur.

Tüm parametreler ve örnek yanıtlar API referansında.

Koddan kart çıkarma

Kart oluşturmak, aynı istekte bir BIN seçer ve kartı bakiyenizden yükler. Alanlar şunlardır:

• bin_id (zorunlu): kartın çıkarılacağı BIN. Seçenekleri GET /bins ile listeleyin.
• amount (zorunlu): bakiyenizden alınan, USD cinsinden ilk yükleme. Minimum $50'dır ve $1 kart çıkarma ücreti bunun üzerine eklenir.
• label: kart için kendi verdiğiniz ad.
• spending_limit: USD cinsinden harcama limiti.
• allowed_categories: kartın kullanılabileceği satıcı kategorileri, örneğin reklam veya yazılım. Diğer her şey reddedilir.
• auto_freeze_at: kartın bakiyesi bu tutarın altına düştüğünde kartı otomatik dondurur.
• metadata: kendi takibiniz için anahtar-değer çiftleri.

Aynı istek Node.js ile:

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();

Başarılı bir çağrı, kart nesnesiyle birlikte 201 döner: id'si, BIN'i, ağı, son dört hanesi, durumu, bakiyesi ve sizin etiket ve metadata'nız. Özet, tam numarayı ve CVV'yi bilerek dışarıda bırakır.

Kart numarasını güvenle almak

GET /cards/{card_id}/details tam kart numarasını, CVV'yi ve son kullanma tarihini döner. Bunu hassas veri olarak ele alın: yanıtı asla loglamayın veya şifrelenmemiş saklamayın ve yalnızca bilgileri gerçekten bir kişiye ya da ödeme sayfasına vermeniz gerektiğinde çekin. Bu uç noktanın hız limiti diğerlerinden daha sıkıdır.

Yükleme, dondurma ve kapatma

• Yükleme: bir amount ile POST /cards/{card_id}/fund, bakiyenizden karta para aktarır. Hemen harcanabilir.
• Fonları geri çekme: POST /cards/{card_id}/withdraw, kartın bakiyesini cüzdanınıza geri döndürür.
• Duraklatma: POST /cards/{card_id}/freeze, bakiyeyi korurken tüm işlemleri askıya alır. unfreeze kartı yeniden etkinleştirir.
• Kapatma: DELETE /cards/{card_id}, kartı kalıcı olarak sonlandırır ve kalan bakiyesini cüzdanınıza iade eder. Geri alınamaz.

API işlemlerine panelde olduğu gibi aynı ücretler uygulanır: çıkarılan kart başına $1, onaylanan işlem başına $0.30 (retler ücretsiz) ve bakiyenizden kartlara ücretsiz yükleme. $300 altındaki yatırmalar %2 ücrete tabidir; $300 ve üzerinde ücret yoktur. Fiyatlandırma bölümüne bakın.

Webhook'lar

Sorgulama yapmak yerine, istediğiniz olayları (veya hepsi için ["*"]) listeleyerek POST /webhooks ile bir HTTPS uç noktası kaydedin. Mevcut olaylar şunlardır:

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

Her teslimat, uç noktanızın secret'ı kullanılarak HMAC-SHA256 ile imzalanır; siz vermezseniz secret sizin için oluşturulur. Payload'a güvenmeden önce imzayı ham istek gövdesi üzerinden yeniden hesaplayın ve sabit sürede karşılaştırın:

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));
}

JSON'u yalnızca doğrulama geçtikten sonra ayrıştırın ve bir olayın birden fazla kez gelme ihtimaline karşı işleyicinizi idempotent yapın.

Hatalar ve hız limitleri

2xx dışındaki her yanıt; dallanabileceğiniz sabit bir error kodu ve insan tarafından okunabilir bir message içeren bir JSON gövdesiyle gelir. Karşılaşacağınız durum kodları 400 (geçersiz parametreler), 401 (eksik veya geçersiz anahtar), 403 (hesap hazır değil veya API etkin değil), 404 (bulunamadı) ve 429'dur (hız limiti aşıldı).

Limitler API anahtarı başına sayılır:

429 alırsanız bekleyin ve üstel geri çekilme (exponential backoff) ile yeniden deneyin.

Güvenilir bir entegrasyon için tasarım ipuçları

• Kart numarasını değil, kart id'sini saklayın. Bilgileri ihtiyaç anında çekin.
• metadata ve label kullanın; kartları müşteri ID'si veya kampanya gibi kendi kayıtlarınıza bağlayın.
• İşlemler ve 3D Secure doğrulamaları için sorgulama yerine webhook'ları tercih edin.
• Tekrarlayan ödemeleri karşılayan kartlarda bir tampon tutun ya da bakiyeleri otomatik yönetmek için auto_freeze_at ve fund kullanın.
• Limitleri planlayın. Hesap planı limitleri yine geçerlidir: Virtual plan işlem başına $5,000 ve aylık $20,000'a izin verirken, $300 veya üzeri tek bir yatırmayla açılan Platinum planda harcama limiti yoktur.

Kod yazmak yerine bir ekip için kart yönetiyorsanız ekipler için sanal kartlar yazısına bakın. Reklam hesabı kullanım senaryoları için reklamlar için sanal kartlar yazısını okuyun. Başlamaya hazır mısınız? Hesap oluşturun.

Sık sorulan sorular

Sanal kart API'si nedir?

Yazılımın ödeme kartlarını otomatik olarak oluşturmasını ve yönetmesini sağlayan bir arayüzdür. USDT Crypto Card'da bu, gizli bir sk_live_ anahtarıyla kimlik doğrulanan, HTTPS üzerinden JSON kullanan bir REST API'dir.

Sandbox veya SDK var mı?

Hayır. Sandbox ortamı ve resmi SDK paketleri yoktur. REST API'yi herhangi bir HTTP istemcisiyle doğrudan çağırırsınız ve her çağrı canlıdır; bu yüzden küçük tutarlarla test edin.

Yeni API anahtarım neden 403 dönüyor?

Hesap henüz hazır değil. onboarding_incomplete, e-postanızı onaylamanız ve ilk yatırmanızı yapmanız gerektiği anlamına gelir. api_not_enabled, desteğin API erişimini henüz açmadığı anlamına gelir.

Webhook'lar nasıl güvence altına alınıyor?

Her teslimat, uç noktanızın secret'ı kullanılarak HMAC-SHA256 ile imzalanır. Payload'a güvenmeden önce imzayı ham gövde üzerinden yeniden hesaplayın ve sabit sürede karşılaştırın.

API kartları panel kartlarıyla aynı maliyette mi?

Evet. Aynı ücretler geçerlidir: kart başına $1, onaylanan işlem başına $0.30, bakiyenizden ücretsiz yükleme ve $300 altında %2 yatırma ücreti.