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é, puis affichez-la avec le code que CardV vous envoie par e-mail. Rangez-la dans votre coffre à secrets.

5. Consultez votre solde :

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_MERCHANT_ID=M00000001     # yours
   export CARDV_API_KEY=cvb2b_...         # from your secret store
   AUTH=(-H "X-Merchant-Id: $CARDV_MERCHANT_ID" -H "X-Api-Key: $CARDV_API_KEY")
   
   curl -sS "$CARDV_BASE/api/v1/balance" "${AUTH[@]}"

6. Trouvez un produit :

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus?search=steam&limit=20" "${AUTH[@]}"

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

7. Obtenez le prix :

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus/S000001/quote?quantity=1" "${AUTH[@]}"

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

8. Passez la commande. Cet appel doit être signé. 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.2500"}
     ]
   }

   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[].display_fields. 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 sept 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 de forfaits mobiles (crédit téléphonique) n'est pas disponible via l'API.

#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.