API Dokümantasyonu — CryptoTopCard Sanal Kart API

Kimlik Doğrulama

API Anahtarları & Kimlik Doğrulama

Tüm API istekleri bir Bearer token gerektirir. API anahtarınızı Panel → Ayarlar → API Anahtarları bölümünden oluşturun.

API Anahtarı Güvenliği

Anahtarınızı istemci tarafı kodda asla açığa çıkarmayın. Ortam değişkenleri kullanın. sk_live_ ön ekli anahtarlar üretim, sk_test_ sandbox içindir.

request-headers

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

Hız Limitleri

1,000

İstek / Dakika

50

Kart Oluşturma / Dakika

10,000

İstek / Saat

Hata Kodları

error-response.json

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

200

İstek başarılı

201

Kaynak oluşturuldu

400

Geçersiz istek parametreleri

401

Eksik veya geçersiz API anahtarı

404

Kaynak bulunamadı

429

Hız limiti aşıldı

Kartlar

Kart Yönetimi

Sanal Visa & Mastercard kartları oluşturun, yönetin ve kontrol edin. Her kart kendi bakiyesi, limitleri ve yaşam döngüsü ile izole edilmiştir.

POST /cards Yeni bir sanal kart oluştur

İstek Gövdesi

Parametre	Tip		Açıklama
bin_id	string	required	BIN tanımlayıcı (örn. `491653`). Mevcut BIN'leri listelemek için `GET /bins` kullanın.
amount	number	required	USD cinsinden başlangıç fonlama tutarı. Min: $1.00, Maks: $5,000.00
label	string	optional	Kart için özel etiket (maks 64 karakter)
spending_limit	number	optional	USD cinsinden aylık harcama limiti. Varsayılan: BIN maksimumu.
allowed_categories	string[]	optional	Beyaz listeye alınacak MCC kategorileri (örn. `["advertising", "software"]`)
auto_freeze_at	number	optional	Bakiye bu tutarın altına düştüğünde otomatik dondur
metadata	object	optional	Dahili takibiniz için anahtar-değer çiftleri (maks 20 anahtar)

Örnek İstek

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

Yanıt 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 Filtreler ve sayfalama ile tüm kartları listele

Sorgu Parametreleri

Parametre	Tip		Açıklama
status	string	optional	`active`, `frozen`, `terminated`
bin_id	string	optional	BIN'e göre filtrele
label	string	optional	Etikete göre ara (kısmi eşleşme)
sort	string	optional	`created_at`, `balance`, `last_used`. Varsayılan: `created_at`
order	string	optional	`asc` veya `desc`. Varsayılan: `desc`
page	integer	optional	Sayfa numarası. Varsayılan: `1`
per_page	integer	optional	Sayfa başına öğe (1-100). Varsayılan: `25`

Yanıt 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} Kart özeti al (hassas veri yok)

Hassas veriler olmadan kart bilgilerini döndürür. Tam PAN ve CVV için /cards/{card_id}/details kullanın.

Yanıt 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 Tam PAN, CVV ve son kullanma tarihi al

Hassas Endpoint

Tam kart PAN, CVV ve son kullanma tarihini döndürür. PCI hassas — asla kaydetmeyin veya şifrelenmemiş saklamayın. 30 istek/dk ile sınırlıdır.

Yanıt 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} Kart ayarlarını güncelle

İstek Gövdesi

Parametre	Tip		Açıklama
label	string	optional	Kart etiketini güncelle
spending_limit	number	optional	Aylık harcama limitini güncelle
allowed_categories	string[]	optional	İzin verilen MCC kategorilerini güncelle
auto_freeze_at	number	optional	Otomatik dondurma eşiğini ayarla. Devre dışı bırakmak için `0`.
metadata	object	optional	Mevcut meta verilerle birleştir

Yanıt 200 OK

Güncellenmiş kart nesnesini döndürür.

POST /cards/{card_id}/freeze Kartı geçici olarak askıya al

Tüm işlemleri askıya alır. Bakiye korunur. Kart daha sonra çözülebilir.

Yanıt 200 OK

response.json

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

POST /cards/{card_id}/unfreeze Dondurulmuş kartı yeniden etkinleştir

Dondurulmuş bir karttaki işlemleri yeniden etkinleştirir. status: "active" ile kart nesnesini döndürür.

DELETE /cards/{card_id} Kartı kalıcı olarak sonlandır

Geri Alınamaz İşlem

Kart sonlandırma kalıcıdır. Kalan bakiye anında cüzdanınıza iade edilir.

Yanıt 200 OK

response.json

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

Fonlama

Kart Fonlama

Bireysel kartlara fon ekleyin veya çekin. Fonlar cüzdan bakiyenizden gelir.

POST /cards/{card_id}/fund Karta fon ekle

İstek Gövdesi

Parametre	Tip		Açıklama
amount	number	required	Eklenecek USD tutarı. Min: $1.00, Maks: $5,000.00

Yanıt 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 Fonları cüzdana geri çek

İstek Gövdesi

Parametre	Tip		Açıklama
amount	number	required	Karttan cüzdana çekilecek USD tutarı

Yanıt 200 OK

Güncellenmiş kart ve cüzdan bakiyelerini döndürür.

İşlemler

İşlem Geçmişi

Kartlarınızdaki tüm işlemleri görüntüleyin. Yetkilendirmeler, ödemeler, iadeler ve reddedilmeleri içerir.

GET /transactions Filtrelerle tüm işlemleri listele

Sorgu Parametreleri

Parametre	Tip		Açıklama
card_id	string	optional	Karta göre filtrele
type	string	optional	`authorization`, `settlement`, `refund`, `decline`
from	string	optional	Başlangıç tarihi (ISO 8601)
to	string	optional	Bitiş tarihi (ISO 8601)
merchant	string	optional	Satıcı adına göre ara (kısmi eşleşme)
min_amount	number	optional	Minimum işlem tutarı
max_amount	number	optional	Maksimum işlem tutarı
page	integer	optional	Sayfa numarası. Varsayılan: `1`
per_page	integer	optional	Sayfa başına öğe (1-100). Varsayılan: `50`

Yanıt 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} Tam işlem detaylarını al

Satıcı detayları, MCC kodu, 3DS durumu ve yetkilendirme zaman çizelgesi dahil tam işlem nesnesini döndürür.

Cüzdan

Cüzdan & Depozitolar

Hesap cüzdanınızı yönetin. Kripto yatırın, bakiyeleri kontrol edin ve gelen depozitoları takip edin.

GET /wallet/balance Cüzdan bakiyesi ve istatistikleri al

Yanıt 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 Kripto depozito adreslerini al

Sorgu Parametreleri

Parametre	Tip		Açıklama
currency	string	optional	`btc`, `eth`, `sol`, `usdt`. Tümünü almak için atlayın.

Yanıt 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 Depozito geçmişini listele

Sorgu Parametreleri

Parametre	Tip		Açıklama
status	string	optional	`pending`, `confirmed`, `expired`
currency	string	optional	Kripto para birimine göre filtrele

Yanıt 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

BIN Seçimi

Mevcut BIN aralıklarını yetenekleri, limitleri ve kabul oranları ile listeleyin.

GET /bins Tüm mevcut BIN'leri listele

Yanıt 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

3D Secure Kimlik Doğrulama

3DS sorunlarını ve OTP kodlarını alın. Tüm kartlar otomatik olarak 3DS 2.0'a kaydedilir.

GET /3ds Bekleyen 3DS sorunlarını listele

Sorgu Parametreleri

Parametre	Tip		Açıklama
card_id	string	optional	Karta göre filtrele
status	string	optional	`pending`, `completed`, `expired`

Yanıt 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} Belirli bir 3DS OTP al

OTP kodu dahil tam 3DS sorgulama nesnesini döndürür. OTP'ler 5 dakika sonra sona erer.

Webhooks

Webhooks & Olaylar

Olaylar gerçekleştiğinde gerçek zamanlı bildirimler alın. Yükler HMAC-SHA256 ile imzalanır.

Mevcut Olaylar

card.createdYeni bir kart oluşturuldu

card.frozenBir kart donduruldu

card.unfrozenBir kart çözüldü

card.terminatedBir kart sonlandırıldı

card.fundedKarta fon eklendi

transaction.authorizedİşlem yetkilendirildi

transaction.settledİşlem tamamlandı

transaction.declinedİşlem reddedildi

transaction.refundedİade işlendi

3ds.challenge3DS doğrulaması gerekli

deposit.pendingKripto depozito algılandı

deposit.confirmedKripto depozito onaylandı

İmza Doğrulama

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 Webhook endpoint'i kaydet

İstek Gövdesi

Parametre	Tip		Açıklama
url	string	required	Olayları almak için HTTPS endpoint URL'si
events	string[]	required	Abone olunacak olay türleri. Tümü için `["*"]` kullanın.
secret	string	optional	Özel imza gizli anahtarı. Atlanırsa otomatik oluşturulur.

Yanıt 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 Kayıtlı webhook'ları listele

Tüm kayıtlı webhook endpoint'lerinin olay abonelikleri ve durumları ile dizisini döndürür.

DELETE /webhooks/{webhook_id} Webhook sil

Webhook'u kalıcı olarak kaldırır. Bu endpoint'e artık olay teslim edilmez.

SDKs

SDKs & Kütüphaneler

Yığınınız için resmi istemci kütüphaneleri. Tüm SDK'lar canlı ve sandbox ortamlarını destekler.

Python

pip install cryptotopcard

Node.js

npm i cryptotopcard

Go

go get cryptotopcard

Hızlı Başlangıç — Python

quickstart.py

from cryptotopcard import Client

client = Client("sk_live_your_api_key")

# Kart oluştur
card = client.cards.create(
    bin_id="491653",
    amount=500,
    label="Ad Spend"
)
print(card.id, card.last4)

# Tam kart detaylarını al (PAN, CVV)
details = client.cards.details(card.id)
print(details.pan, details.cvv)

# Kartı fonla
client.cards.fund(card.id, amount=200)

# İşlemleri listele
txns = client.transactions.list(card_id=card.id)
for t in txns.data:
    print(t.merchant.name, t.amount)

Hızlı Başlangıç — Node.js

quickstart.js

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

const client = new CryptoTopCard('sk_live_your_api_key');

// Kart oluştur
const card = await client.cards.create({
  binId: '491653',
  amount: 500,
  label: 'Ad Spend',
});

// 3DS OTP'leri al
const challenges = await client.threeds.list({
  cardId: card.id,
  status: 'pending',
});

// Webhook'ları kur
await client.webhooks.create({
  url: 'https://yourapp.com/hooks',
  events: ['transaction.authorized', '3ds.challenge'],
});

API Referans

API Anahtarları & Kimlik Doğrulama

API Anahtarı Güvenliği

Kart Yönetimi

Hassas Endpoint

Geri Alınamaz İşlem

Kart Fonlama

İşlem Geçmişi

Cüzdan & Depozitolar

BIN Seçimi

3D Secure Kimlik Doğrulama

Webhooks & Olaylar

SDKs & Kütüphaneler

Python

Node.js

Go

Tekrar hoş geldiniz

Hesap Oluştur

Hesap Oluşturuldu