Documentation API — CryptoTopCard API Cartes Virtuelles

Authentification

Clés API & Authentification

Toutes les requêtes API nécessitent un token Bearer. Générez votre clé API depuis Tableau de bord → Paramètres → Clés API.

Sécurité des Clés API

N'exposez jamais votre clé dans le code côté client. Utilisez des variables d'environnement. Les clés préfixées par sk_live_ sont de production, sk_test_ sont de sandbox.

request-headers

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

Limites de Débit

1,000

Requêtes / Minute

50

Créations de Carte / Minute

10,000

Requêtes / Heure

Codes d'Erreur

error-response.json

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

200

Requête réussie

201

Ressource créée

400

Paramètres de requête invalides

401

Clé API manquante ou invalide

404

Ressource non trouvée

429

Limite de débit dépassée

Cartes

Gestion des Cartes

Créez, gérez et contrôlez des cartes virtuelles Visa & Mastercard. Chaque carte est isolée avec son propre solde, ses limites et son cycle de vie.

POST /cards Émettre une nouvelle carte virtuelle

Corps de la Requête

Paramètre	Type		Description
bin_id	string	required	Identifiant BIN (ex. `491653`). Utilisez `GET /bins` pour lister les BINs disponibles.
amount	number	required	Montant de financement initial en USD. Min : $1.00, Max : $5,000.00
label	string	optional	Étiquette personnalisée pour la carte (max 64 caractères)
spending_limit	number	optional	Limite de dépenses mensuelle en USD. Par défaut le maximum du BIN.
allowed_categories	string[]	optional	Catégories MCC à autoriser (ex. `["advertising", "software"]`)
auto_freeze_at	number	optional	Geler automatiquement lorsque le solde tombe en dessous de ce montant
metadata	object	optional	Paires clé-valeur pour votre suivi interne (max 20 clés)

Exemple de Requête

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

Réponse 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 Lister toutes les cartes avec filtres et pagination

Paramètres de Requête

Paramètre	Type		Description
status	string	optional	`active`, `frozen`, `terminated`
bin_id	string	optional	Filtrer par BIN
label	string	optional	Rechercher par étiquette (correspondance partielle)
sort	string	optional	`created_at`, `balance`, `last_used`. Par défaut: `created_at`
order	string	optional	`asc` ou `desc`. Par défaut: `desc`
page	integer	optional	Numéro de page. Par défaut: `1`
per_page	integer	optional	Éléments par page (1-100). Par défaut: `25`

Réponse 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} Obtenir le résumé de carte (sans données sensibles)

Retourne les infos de carte sans données sensibles. Utilisez /cards/{card_id}/details pour le PAN complet et CVV.

Réponse 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 Obtenir le PAN complet, CVV et expiration

Endpoint Sensible

Retourne le PAN complet, CVV et expiration. Données PCI sensibles — ne jamais enregistrer ni stocker en clair. Limité à 30 req/min.

Réponse 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} Mettre à jour les paramètres de carte

Corps de la Requête

Paramètre	Type		Description
label	string	optional	Mettre à jour l'étiquette de carte
spending_limit	number	optional	Mettre à jour la limite de dépenses mensuelle
allowed_categories	string[]	optional	Mettre à jour les catégories MCC autorisées
auto_freeze_at	number	optional	Définir le seuil de gel automatique. `0` pour désactiver.
metadata	object	optional	Fusionner avec les métadonnées existantes

Réponse 200 OK

Retourne l'objet carte mis à jour.

POST /cards/{card_id}/freeze Suspendre temporairement une carte

Suspend toutes les transactions. Le solde est préservé. La carte peut être dégelée ultérieurement.

Réponse 200 OK

response.json

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

POST /cards/{card_id}/unfreeze Réactiver une carte gelée

Réactive les transactions sur une carte gelée. Retourne l'objet carte avec status: "active".

DELETE /cards/{card_id} Résilier définitivement une carte

Action Irréversible

La résiliation d'une carte est permanente. Le solde restant est retourné à votre portefeuille instantanément.

Réponse 200 OK

response.json

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

Financement

Financement de Cartes

Ajoutez ou retirez des fonds de cartes individuelles. Les fonds proviennent du solde de votre portefeuille.

POST /cards/{card_id}/fund Ajouter des fonds à une carte

Corps de la Requête

Paramètre	Type		Description
amount	number	required	Montant en USD à ajouter. Min : $1.00, Max : $5,000.00

Réponse 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 Retirer des fonds vers le portefeuille

Corps de la Requête

Paramètre	Type		Description
amount	number	required	Montant en USD à retirer de la carte vers le portefeuille

Réponse 200 OK

Retourne les soldes mis à jour de la carte et du portefeuille.

Transactions

Historique des Transactions

Consultez toutes les transactions de vos cartes. Inclut autorisations, règlements, remboursements et refus.

GET /transactions Lister toutes les transactions avec filtres

Paramètres de Requête

Paramètre	Type		Description
card_id	string	optional	Filtrer par carte
type	string	optional	`authorization`, `settlement`, `refund`, `decline`
from	string	optional	Date de début (ISO 8601)
to	string	optional	Date de fin (ISO 8601)
merchant	string	optional	Rechercher par nom de marchand (correspondance partielle)
min_amount	number	optional	Montant minimum de transaction
max_amount	number	optional	Montant maximum de transaction
page	integer	optional	Numéro de page. Par défaut: `1`
per_page	integer	optional	Éléments par page (1-100). Par défaut: `50`

Réponse 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} Obtenir les détails complets de transaction

Retourne l'objet transaction complet incluant les détails du marchand, le code MCC, le statut 3DS et la chronologie d'autorisation.

Portefeuille

Portefeuille & Dépôts

Gérez votre portefeuille de compte. Déposez des cryptos, vérifiez les soldes et suivez les dépôts entrants.

GET /wallet/balance Obtenir le solde et les statistiques du portefeuille

Réponse 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 Obtenir les adresses de dépôt crypto

Paramètres de Requête

Paramètre	Type		Description
currency	string	optional	`btc`, `eth`, `sol`, `usdt`. Omettre pour obtenir tous.

Réponse 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 Lister l'historique des dépôts

Paramètres de Requête

Paramètre	Type		Description
status	string	optional	`pending`, `confirmed`, `expired`
currency	string	optional	Filtrer par cryptomonnaie

Réponse 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

Sélection de BIN

Listez les plages BIN disponibles avec leurs capacités, limites et taux d'acceptation.

GET /bins Lister tous les BINs disponibles

Réponse 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

Authentification 3D Secure

Récupérez les défis 3DS et les codes OTP. Toutes les cartes sont inscrites en 3DS 2.0 automatiquement.

GET /3ds Lister les défis 3DS en attente

Paramètres de Requête

Paramètre	Type		Description
card_id	string	optional	Filtrer par carte
status	string	optional	`pending`, `completed`, `expired`

Réponse 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} Obtenir un OTP 3DS spécifique

Retourne l'objet défi 3DS complet incluant le code OTP. Les OTP expirent après 5 minutes.

Webhooks

Webhooks & Événements

Recevez des notifications en temps réel lorsque des événements se produisent. Les charges utiles sont signées avec HMAC-SHA256.

Événements Disponibles

card.createdUne nouvelle carte a été émise

card.frozenUne carte a été gelée

card.unfrozenUne carte a été dégelée

card.terminatedUne carte a été résiliée

card.fundedDes fonds ont été ajoutés à une carte

transaction.authorizedTransaction autorisée

transaction.settledTransaction réglée

transaction.declinedTransaction refusée

transaction.refundedRemboursement traité

3ds.challengeVérification 3DS requise

deposit.pendingDépôt crypto détecté

deposit.confirmedDépôt crypto confirmé

Vérification de Signature

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 Enregistrer un endpoint de webhook

Corps de la Requête

Paramètre	Type		Description
url	string	required	URL de l'endpoint HTTPS pour recevoir les événements
events	string[]	required	Types d'événements à souscrire. Utilisez `["*"]` pour tous.
secret	string	optional	Secret de signature personnalisé. Généré automatiquement si omis.

Réponse 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 Lister les webhooks enregistrés

Retourne le tableau de tous les endpoints webhook enregistrés avec leurs abonnements aux événements et leur statut.

DELETE /webhooks/{webhook_id} Supprimer un webhook

Supprime définitivement le webhook. Aucun événement ne sera plus livré à cet endpoint.

SDKs

SDKs & Bibliothèques

Bibliothèques client officielles pour votre stack. Tous les SDKs supportent les environnements de production et sandbox.

Python

pip install cryptotopcard

Node.js

npm i cryptotopcard

Go

go get cryptotopcard

Démarrage Rapide — Python

quickstart.py

from cryptotopcard import Client

client = Client("sk_live_your_api_key")

# Créer une carte
card = client.cards.create(
    bin_id="491653",
    amount=500,
    label="Ad Spend"
)
print(card.id, card.last4)

# Obtenir les détails complets (PAN, CVV)
details = client.cards.details(card.id)
print(details.pan, details.cvv)

# Financer la carte
client.cards.fund(card.id, amount=200)

# Lister les transactions
txns = client.transactions.list(card_id=card.id)
for t in txns.data:
    print(t.merchant.name, t.amount)

Démarrage Rapide — Node.js

quickstart.js

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

const client = new CryptoTopCard('sk_live_your_api_key');

// Créer une carte
const card = await client.cards.create({
  binId: '491653',
  amount: 500,
  label: 'Ad Spend',
});

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

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

API Référence

Clés API & Authentification

Sécurité des Clés API

Gestion des Cartes

Endpoint Sensible

Action Irréversible

Financement de Cartes

Historique des Transactions

Portefeuille & Dépôts

Sélection de BIN

Authentification 3D Secure

Webhooks & Événements

SDKs & Bibliothèques

Python

Node.js

Go

Bon retour

Créer un compte

Compte créé