Catalogue et commandes

Voir aussi : Authentification · Conventions · Webhooks

#Compte et solde

#Compte

GET/api/v1/account affiche les informations de votre entreprise et indique si l'accès API est activé.

{
  "merchant_id": "M00000001",
  "name": "Acme Shop",
  "legal_name": "Acme Shop Ltd",
  "billing_email": "[email protected]",
  "status": "active",
  "kyb_status": "approved",
  "api_access_enabled": true,
  "default_currency": "USD",
  "purchase_limits": {
    "currency": "USD",
    "verified": true,
    "max_order_amount": "1000.00",
    "daily_order_amount_limit": "10000.00",
    "daily_order_count_limit": 1000,
    "used_today_amount": "120.50",
    "used_today_count": 3,
    "day_resets_at": "2026-10-01T00:00:00+00:00"
  }
}

• default_currency est la devise de votre portefeuille. Tous les prix que vous payez sont dans cette devise.
• api_access_enabled passe à true dès que CardV a validé votre entreprise.

#Solde

GET/api/v1/balance indique combien vous pouvez dépenser.

{
  "currency": "USD",
  "balance": "1520.40",
  "reserved_amount": "0.00",
  "available_balance": "1520.40",
  "low_balance_threshold": "200.00",
  "low_balance_notified_at": null,
  "is_active": true
}

• available_balance est le montant que vous pouvez dépenser tout de suite : balance moins reserved_amount.
• Une commande supérieure à available_balance est refusée, et rien n'est débité.
• low_balance_threshold est le seuil qui déclenche l'e-mail de solde bas. Vous le réglez dans le Portail.
• Pour ajouter des fonds, passez par le Portail.

#Taux de change

GET/api/v1/fx-rates?quote=EUR donne le taux de change de l'USD vers une autre devise.

Utilisez-le si votre boutique vend dans une devise autre que l'USD. CardV débite toujours votre portefeuille en USD. Ce taux sert uniquement à fixer vos propres prix.

{
  "base": "USD",
  "quote": "EUR",
  "rate": "0.9234",
  "as_of": "2026-10-11T07:05:00Z"
}

• quote est un code de devise ISO 4217, par exemple EUR, GBP ou JPY.
• base est facultatif. Seul USD est pris en charge.
• rate indique combien d'unités de quote vous obtenez pour 1 USD. C'est une chaîne décimale. Ne la lisez pas comme un float.
• as_of indique quand CardV a mis à jour ce taux pour la dernière fois. Les taux sont mis à jour toutes les heures.
• quote=USD renvoie "rate": "1".
• Enregistrez le taux de votre côté. Quelques appels par jour suffisent.

Signez cette requête comme les autres. Le chemin signé inclut la chaîne de requête, par exemple /api/v1/fx-rates?quote=EUR.

#Produits (SKU)

Un SKU est un produit que vous pouvez acheter, par exemple « Steam Wallet 10 USD ». Son identifiant ressemble à S000456. C'est sur les SKU que vous demandez un prix et passez commande.

#Modèles de produit

Chaque SKU relève de l'un de ces modèles. Lisez denomination_type et product_type pour les distinguer.

• vertical est la gamme de produits, pas le modèle. Une recharge directe peut avoir vertical: "gift_card".
• Tout SKU à montant fixe ou libre peut être livré sous forme de lien d'utilisation CardV au lieu d'un code. Le SKU a alors delivery_mode: "voucher". Vous recevez un lien (delivery_type: "link", le lien est dans redeem_url). Votre client l'ouvre pour obtenir le code. Transmettez-le à votre client comme un code.

GET/api/v1/skus liste les SKU que vous pouvez acheter. Exemple :

GET /api/v1/skus?search=steam&region=US&limit=50&offset=0

Filtres (tous facultatifs) :

Pagination : envoyez limit (100 par défaut, 500 au maximum) et offset. Augmentez offset à chaque appel jusqu'à ce qu'il atteigne count.

{
  "count": 7,
  "limit": 2,
  "results": [
    {
      "sku_id": "S000456",
      "product_id": "P000123",
      "name": "Steam Wallet 10 USD",
      "product_name": "Steam Wallet US",
      "brand": "Steam",
      "region": "US",
      "vertical": "gift_card",
      "product_type": "pin_code",
      "denomination_type": "fixed",
      "denomination_value": "10",
      "face_currency": "USD",
      "merchant_price": "9.25",
      "merchant_price_min": "9.25",
      "merchant_price_max": "9.25",
      "settlement_currency": "USD",
      "availability": "available",
      "min_quantity": 1,
      "max_quantity": 100,
      "required_input_schema": [],
      "...": "more fields"
    },
    {
      "sku_id": "S006126",
      "product_id": "P002210",
      "name": "Apple ES",
      "product_name": "Apple ES",
      "brand": "Apple",
      "region": "ES",
      "vertical": "gift_card",
      "product_type": "pin_code",
      "denomination_type": "range",
      "denomination_value": "0",
      "min_face_value": "2",
      "max_face_value": "250",
      "amount_step": null,
      "face_currency": "EUR",
      "merchant_price": "2.28",
      "merchant_price_min": "2.28",
      "merchant_price_max": "284.15",
      "price_label": "From 2.28 USD",
      "settlement_currency": "USD",
      "availability": "available",
      "...": "more fields"
    }
  ],
  "filter_options": {"brands": [], "regions": [], "categories": [], "verticals": []}
}

GET/api/v1/skus/{sku_id} renvoie un seul SKU, avec les mêmes champs.

Les champs les plus utiles :

Conseils :

• Vous ne voyez que les SKU actifs et ouverts à votre compte. Les autres renvoient 404.
• Synchronisez la liste des SKU toutes les 5 à 15 minutes. Demandez toujours le prix juste avant de commander.
• Affichez à vos clients les prix de votre liste synchronisée. N'appelez pas l'endpoint de prix à chaque page vue ou pour chaque visiteur.
• Les prix des SKU à montant libre suivent le coût fournisseur et peuvent changer plusieurs fois par jour. Mettez à jour merchant_price_min et merchant_price_max lors de votre synchronisation des SKU.
• filter_options liste les marques, les pays et les gammes de produits sur lesquels vous pouvez filtrer.

#Synchroniser par produit

Si votre boutique affiche une page par produit avec un choix de montant, synchronisez les produits plutôt que les SKU. GET/api/v1/products liste les produits. Chaque produit contient tous les SKU que vous pouvez y acheter.

GET /api/v1/products?brand=Steam&region=GB&limit=50&offset=0

Les filtres et la pagination sont les mêmes que pour GET/api/v1/skus. count compte les produits et sku_count leurs SKU.

{
  "count": 1,
  "sku_count": 4,
  "limit": 50,
  "results": [
    {
      "product_id": "P000123",
      "product_name": "Steam Wallet UK",
      "brand": "Steam",
      "category": "Gaming",
      "region": "GB",
      "product_type": "pin_code",
      "image_url": "https://b2b.cardv.net/api/v1/catalog-assets/steam.png",
      "required_input_schema": [],
      "skus": [
        {
          "sku_id": "S000456",
          "name": "Steam Wallet 5 GBP",
          "label": "5 GBP",
          "denomination_type": "fixed",
          "denomination_value": "5",
          "face_currency": "GBP",
          "merchant_price": "7.61",
          "settlement_currency": "USD",
          "availability": "available",
          "min_quantity": 1,
          "max_quantity": 100,
          "...": "more fields"
        }
      ]
    }
  ],
  "filter_options": {"brands": [], "regions": [], "categories": [], "verticals": []}
}

GET/api/v1/products/{product_id} renvoie un produit avec ses SKU, ainsi que description, redemption_instructions, terms et disclaimer.

• Chaque SKU de skus a les mêmes champs et les mêmes valeurs que dans GET/api/v1/skus. Devis et commande se font comme d'habitude avec son sku_id.
• Utilisez label comme texte d'option, par exemple 5 GBP ou Tinder Plus 1 Month. Certains produits sont des forfaits, pas des montants.
• Un produit a une seule devise de valeur faciale et un seul type de montant. Un SKU à montant libre est toujours un produit à part.
• La liste n'inclut pas les textes longs. Lisez-les une fois par produit avec GET/api/v1/products/{product_id}.

#Montants fixes et montants libres

La plupart des SKU ont une valeur fixe, par exemple 10 USD. D'autres ont un montant libre dans une fourchette : votre client choisit le montant, par exemple entre 5 et 500 USD.

Pour un SKU à montant libre, amount doit être compris entre min_face_value et max_face_value. Il est exprimé en face_currency.

Prix d'un SKU à montant libre. Dans les listes de SKU et de produits, merchant_price et price_label correspondent uniquement au prix de min_face_value. merchant_price_min et merchant_price_max donnent le prix du montant minimum et du montant maximum. Le prix d'un montant intermédiaire n'est un simple multiple d'aucun des deux. Avant de fixer votre prix de vente ou de commander, demandez un devis avec le amount exact et envoyez son merchant_price comme expected_unit_price.

Certains SKU à montant libre ont aussi un amount_step. S'il n'est pas null, amount doit en être un multiple. Par exemple, avec "amount_step": "1", vous pouvez envoyer 25 mais pas 25.50. Un devis ou une commande dont le montant ne respecte pas le pas renvoie HTTP 400 et rien n'est débité.

#Recharges directes

Certains produits rechargent directement le compte de votre client, par exemple un compte de jeu. Pour ces produits, CardV a besoin des informations du compte. Le SKU indique lesquelles :

"required_input_schema": [
  {"key": "player_id", "label": "Player ID", "type": "text", "required": true},
  {"key": "server", "label": "Server", "type": "text", "required": false}
]

Envoyez les valeurs dans le champ inputs de la ligne de commande, avec chaque key :

"inputs": {"player_id": "123456789", "server": "EU"}

• Un champ est obligatoire, sauf s'il porte "required": false. type est une indication pour le champ de votre formulaire, par exemple text.
• S'il manque une valeur obligatoire, la commande est refusée avec une erreur items.
• Ces valeurs sont des données personnelles de votre client. Protégez-les (voir Sécurité).

#Prix actuel

Une demande de prix (quote) vous donne le prix actuel pour une quantité donnée.

GET /api/v1/skus/S000456/quote?quantity=2
GET /api/v1/skus/S000789/quote?quantity=1&amount=25.00

{
  "sku_id": "S000456",
  "settlement_currency": "USD",
  "merchant_price": "9.25",
  "quantity": 2,
  "total_price": "18.50",
  "min_quantity": 1,
  "max_quantity": 100,
  "availability": "available"
}

• Le prix obtenu n'est pas garanti. Il peut changer à tout moment.
• Demandez le prix une seule fois, au moment où votre client passe au paiement, avec un délai d'attente court, par exemple 5 secondes. Si la demande expire, continuez d'afficher votre prix synchronisé et réessayez ; n'affichez jamais une page d'erreur parce qu'une demande de prix a été lente.
• Pour vous protéger, renvoyez merchant_price dans expected_unit_price quand vous commandez. Envoyez le prix obtenu par une demande de prix, pas un prix que vous avez calculé vous-même : il doit correspondre exactement, au centime près. Si le prix a changé entre-temps, CardV refuse la commande et ne débite rien.
• Une quantité ou un montant hors limites, ou un montant qui n'est pas un multiple de amount_step, renvoie HTTP 400 avec une erreur quantity ou amount.

#Passer une commande

POST/api/v1/orders achète un ou plusieurs SKU et les paie avec votre portefeuille. Comme tout appel, il doit être signé.

{
  "external_order_id": "SHOP-20260929-10001",
  "items": [
    {"sku_id": "S000456", "quantity": 2, "expected_unit_price": "9.25"},
    {"sku_id": "S000789", "amount": "25.00", "expected_unit_price": "23.75"},
    {
      "sku_id": "S000900",
      "expected_unit_price": "4.90",
      "inputs": {"player_id": "123456789"}
    }
  ]
}

Dès que CardV accepte la commande, il débite immédiatement le montant total de votre portefeuille. La livraison démarre ensuite en arrière-plan.

La réponse est un HTTP 201 :

{
  "idempotent_replay": false,
  "order": {
    "order_id": "O-00001234",
    "external_order_id": "SHOP-20260929-10001",
    "status": "accepted",
    "total_amount": "46.20",
    "...": "more fields"
  }
}

Enregistrez order.order_id. Cette réponse ne contient jamais de codes : vous les récupérerez ensuite (voir Consulter une commande).

#Commandes refusées

Une commande refusée renvoie HTTP 400 et rien n'est débité. La clé d'erreur indique la raison :

Exemple de changement de prix :

{
  "items": "SKU S000456 price changed from 9.25 to 9.41 USD; refresh quote and confirm again."
}

Votre compte a des plafonds par commande, de dépense quotidienne et de nombre de commandes par jour. GET/api/v1/account les indique dans purchase_limits, avec ce que vous avez déjà utilisé aujourd'hui. 0 signifie aucun plafond. Les plafonds quotidiens repartent à zéro à 00:00 UTC.

#Renvoyer sans risque

Votre numéro de commande (external_order_id) vous évite d'acheter deux fois. Si vous renvoyez la même commande avec le même numéro, CardV ne vous débite pas une seconde fois. Il vous renvoie la commande déjà enregistrée.

« La même commande » signifie les mêmes lignes, dans le même ordre, avec les mêmes SKU, quantités, montants et inputs. Si vous envoyez expected_unit_price, il doit être identique à celui de la première commande.

Une commande en double est détectée avant la vérification du solde et du prix. Elle renvoie donc toujours la première commande, même si le prix a changé depuis.

#Renvoyer une commande pas à pas

Si vous n'obtenez pas de réponse claire, renvoyez simplement la même commande.

POST /orders avec le numéro de commande R
 ├─ 201 ou 200 → enregistrez order_id. Terminé.
 ├─ 400 items / balance / risk → aucune commande n'a été créée.
 │      Corrigez la cause et renvoyez. Vous pouvez réutiliser R.
 ├─ 400 external_order_id → R correspond à une autre commande. Arrêtez et vérifiez.
 ├─ 403 erreur de signature → signez à nouveau et envoyez le même corps.
 ├─ 429 → attendez Retry-After, signez à nouveau, envoyez le même corps.
 └─ délai dépassé, 5xx ou connexion perdue
        → renvoyez le même corps avec le même R.
          Vous recevez 201 (le premier envoi n'était pas arrivé) ou 200 (il était arrivé).

Règles :

• Ne créez jamais un nouveau numéro de commande parce qu'une réponse s'est perdue. Si la première requête était bien arrivée, un nouveau numéro vous ferait tout acheter deux fois.
• Chaque renvoi demande un nouvel horodatage, un nouveau nonce et une nouvelle signature. Le corps, lui, ne change pas.

#Consulter une commande

GET/api/v1/orders/{order_id} renvoie la commande, son statut et ses codes.

{
  "order_id": "O-00001234",
  "external_order_id": "SHOP-20260929-10001",
  "status": "succeeded",
  "currency": "USD",
  "total_amount": "18.50",
  "created_at": "2026-09-29T08:15:30.123456Z",
  "updated_at": "2026-09-29T08:15:41.004211Z",
  "items": [
    {
      "sku_id": "S000456",
      "product_name": "Steam Wallet US",
      "quantity": 2,
      "unit_price": "9.25",
      "total_price": "18.50",
      "delivery_count": 2,
      "deliveries": [{"...": "see Codes below"}]
    }
  ],
  "...": "more fields"
}

• total_amount est le montant débité au moment où la commande a été acceptée.
• items[].unit_price est le prix bloqué pour cette commande.
• items[].deliveries contient les codes complets. Traitez cette réponse comme confidentielle.
• invoice_url et delivery_file_url sont les chemins de la facture et du fichier CSV des codes. Ils sont réservés au Portail : avec une clé API, ils renvoient HTTP 403.
• La réponse contient aussi id (un ancien numéro, à ne pas utiliser), events (un historique destiné à l'affichage) et l'avancement de la livraison ligne par ligne. Vous pouvez les ignorer.
• Un numéro de commande inconnu renvoie HTTP 404.

#Statut de la commande et codes

#Statut

accepted ──► processing ──► succeeded
                  │
                  ├──► partially_succeeded   (une partie des lignes livrée, le reste non)
                  │
                  └──► failed ──► refunded   (argent rendu à votre portefeuille)

Si vous n'utilisez pas les webhooks, interrogez l'API à ce rythme : après 5 secondes, puis 10 s, 30 s, 60 s, puis toutes les 5 minutes. Restez sous la limite de requêtes. La plupart des commandes se terminent en quelques secondes. Certaines demandent une vérification manuelle et peuvent prendre plusieurs heures.

#Codes

Chaque unité livrée correspond à un objet dans items[].deliveries :

{
  "status": "stored",
  "delivery_type": "card_pin",
  "card_number": "X1234",
  "pin_code": "9876",
  "redeem_url": "",
  "expiry_date": "2027-09-29",
  "instructions": "Redeem at ..."
}

• Remettez à votre client tous les champs non vides : card_number, pin_code, redeem_url, expiry_date et instructions.
• delivery_type indique ce que vous avez reçu : code, card_pin, link, code_link ou qr.
• Gardez redeem_url secret, comme un code.
• Ne supprimez, ne masquez et n'annulez jamais un code parce que expiry_date est vide. N'affichez une date d'expiration à votre client que si elle n'est pas vide.
• Ne remettez jamais à votre client une unité dont le status est voided.
• Les produits à recharge directe n'ont généralement pas de livraison. succeeded signifie que le compte a été rechargé.
• Les webhooks ne contiennent jamais de codes. Consultez la commande après avoir reçu un webhook.