API marchand CardV

#Documentation

#Environnements

La Sandbox est une copie de test séparée de CardV, avec de l'argent fictif. Les clés, les soldes, les commandes et les identifiants de produits diffèrent d'un environnement à l'autre.

#Démarrage rapide

1. Faites une demande de compte marchand dans le Portail et confirmez votre adresse e-mail.

2. Attendez la validation. CardV vérifie votre entreprise. Vous recevez ensuite un Merchant ID (votre identifiant marchand), par exemple M00000001.

3. Ouvrez la Sandbox. Connectez-vous au Portail et choisissez Sandbox dans l'en-tête. Vous disposez de 1 000 USD d'argent de test.

4. Créez une clé API. Dans le Portail, allez dans Integrations → API keys. Créez une clé. Le Portail affiche le key ID et le secret de signature une seule fois. Rangez le secret dans votre coffre à secrets.

5. Consultez votre solde :

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_KEY_ID=ck_test_...            # shown in the Portal
   export CARDV_SIGNING_SECRET=cs_test_...    # from your secret store
   
   cardv_get() {  # every call is signed, see Authentication
     local ts nonce sig
     ts=$(date +%s); nonce=$(openssl rand -hex 16)
     sig=$(printf 'GET\n%s\n%s\n%s\n%s' "$1" "$ts" "$nonce" \
       e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 \
       | openssl dgst -sha256 -hmac "$CARDV_SIGNING_SECRET" -hex | sed 's/^.*= //')
     curl -sS "$CARDV_BASE$1" -H "X-Key-Id: $CARDV_KEY_ID" \
       -H "X-Timestamp: $ts" -H "X-Nonce: $nonce" -H "X-Signature: $sig"
   }
   
   cardv_get "/api/v1/balance"

6. Trouvez un produit :

   ShellCopy

   cardv_get "/api/v1/skus?search=steam&limit=20"

   Choisissez-en un avec "availability": "available" et notez son sku_id.

7. Obtenez le prix :

   ShellCopy

   cardv_get "/api/v1/skus/S000001/quote?quantity=1"

   Notez merchant_price : c'est ce que vous payez par unité.

8. Passez la commande. Signez-la comme tout appel. Reprenez un exemple de Authentification avec ce corps de requête :

   JSONCopy

   {
     "external_order_id": "TEST-0001",
     "items": [
       {"sku_id": "S000001", "quantity": 1, "expected_unit_price": "9.25"}
     ]
   }

   Vous recevez un HTTP 201 avec un numéro de commande CardV, par exemple O-00001234.

9. Récupérez les codes. Appelez GET/api/v1/orders/O-00001234 jusqu'à ce que le statut soit succeeded. Les codes se trouvent dans items[].deliveries[] : card_number, pin_code et redeem_url. Vous pouvez aussi recevoir un webhook quand la commande est terminée.

10. Passez en production une fois la liste de contrôle Sandbox validée.

Les identifiants et les prix ci-dessus sont des exemples. Utilisez les valeurs renvoyées par votre propre catalogue.

#L'API en bref

L'API compte seize endpoints. Tous les chemins commencent par /api/v1.

Tout autre endpoint renvoie HTTP 403 s'il est appelé avec une clé API :

{"detail": "This operation is only available in the Merchant Portal."}

La recharge mobile est décrite dans Recharge mobile.

#Identifiants

Enregistrez les identifiants sous forme de texte, sans chercher à les décomposer. Voir Conventions.

#Ce qui se fait dans le Portail marchand

• L'ajout de fonds au portefeuille et l'alerte e-mail en cas de solde bas
• L'historique des commandes, la recherche et les exports CSV
• Les factures des commandes
• Les mouvements du portefeuille et le rapprochement comptable
• La configuration des webhooks, l'historique des envois et les renvois
• Les clés API
• La liste d'IP autorisées
• Les membres de l'équipe et leurs rôles
• Le journal d'audit
• La validation en deux étapes (2FA)
• Le passage de Live à Sandbox et inversement

#Compatibilité et support

Nous pouvons ajouter de nouveaux champs de réponse et de nouveaux statuts sans préavis. Ignorez les champs que vous ne connaissez pas. Considérez un statut de commande inconnu comme « pas encore terminée ». Ne vous fiez pas au texte des messages d'erreur.

Écrivez à [email protected] en indiquant votre Merchant ID, l'environnement, les numéros de commande, l'heure (UTC) et le code HTTP. N'envoyez jamais de clés API, de signatures, de secrets de webhook ni de codes de cartes.