Passer au contenu principal
L’API de paiement vous permet de créer de manière programmatique des sessions d’achat pour vos clients. Cela est utile pour les vitrines personnalisées, les intégrations ou les flux de vente automatisés.
Types de produits non pris en charge : les produits suivants ne peuvent pas être utilisés pour initier un checkout via l’API :
  • Produits de type Service
  • Produits de type Coaching
  • Produits avec tarification prix libre
Pour ceux-ci, redirigez vos clients vers votre boutique Chariow ou utilisez le widget Snap intégré sur votre site web.
Toutes les ventes initiées via l’API checkout auront leur Canal défini sur « API » dans votre tableau de bord. Cela vous aide à identifier et suivre les ventes provenant de vos intégrations API séparément des autres canaux comme votre vitrine ou le widget Snap.

Achats répétés

La possibilité d’acheter un produit plusieurs fois dépend du type de produit :
Pour les types de produits bloqués, si l’accès d’un client a été révoqué (par exemple après un remboursement), il pourra acheter le produit à nouveau. Le système vérifie uniquement les accès actifs.

Aperçu du flux de paiement

L’API de paiement Chariow gère le flux d’achat complet de l’initiation à la finalisation :
Le produit doit être publié avant d’initier un paiement. Les produits non publiés retourneront une erreur 404.
1

Initier le paiement

Appelez le point de terminaison /checkout avec l’ID du produit et les détails du client
2

Traiter la réponse

Vérifiez le champ step dans la réponse :
  • payment : Redirigez le client vers checkout_url pour le paiement
  • completed : Vente finalisée immédiatement (produits gratuits)
  • already_purchased : Le client possède déjà ce produit
3

Traiter le paiement

Le client finalise le paiement sur la page de paiement hébergée et sécurisée, avec les moyens disponibles dans son pays
4

Recevoir le webhook

Recevez une notification des changements de statut de vente via webhooks (recommandé)
5

Livrer le produit

Le client reçoit automatiquement l’accès aux fichiers, licences, cours, etc.

Types de produits pris en charge

L’API de paiement prend en charge les types de produits Chariow suivants :
  • Produits téléchargeables : Fichiers numériques (PDF, logiciels, médias)
  • Cours : Contenu éducatif avec leçons et chapitres
  • Licences : Clés de licence logicielle avec gestion des activations
  • Bundles : Collections de plusieurs produits
Les types de produits Service et Coaching ne sont pas pris en charge via l’API publique. Pour ces produits, redirigez vos clients vers votre boutique Chariow ou utilisez le widget Snap. Les produits à tarification prix libre ne sont pas non plus pris en charge.

Initier un paiement

Créez une nouvelle session de paiement :

Paramètres de la requête

Champs d’adresse de livraison

Lorsque le produit a l’option “Exiger une adresse de livraison” activée, vous devez envoyer un objet shipping dans votre requête de paiement :
Ces champs sont requis uniquement lorsque le produit a la livraison activée. Si la livraison n’est pas requise, l’objet shipping est ignoré. Les champs d’adresse envoyés à la racine du corps de la requête ne sont pas lus.

Exemple avec adresse de livraison

États de réponse du paiement

La réponse de paiement inclut un champ step indiquant l’état actuel :

En attente de paiement

Pour les produits payants, vous recevrez une URL de paiement :
L’objet purchase est abrégé ici ; il a la même structure qu’une vente renvoyée par Lister les ventes.
Redirigez le client vers checkout_url pour finaliser son paiement. L’URL contient le pays et le numéro de téléphone de l’acheteur en paramètres de requête afin de préremplir le formulaire de paiement : utilisez-la telle quelle. gateway identifie la passerelle de paiement qui traite le paiement ; traitez cette valeur comme une chaîne opaque.

Finalisé (produits gratuits)

Pour les produits gratuits, la vente est finalisée immédiatement :
Un produit payant est aussi finalisé immédiatement lorsqu’une réduction ramène le montant à zéro.

Déjà acheté

Si le client possède déjà le produit :
Aucune vente n’est créée dans ce cas.

URL de redirection personnalisées

Vous pouvez spécifier une URL de redirection personnalisée pour envoyer les clients vers votre propre page de remerciement après finalisation du paiement :
L’URL de redirection doit être une URL active valide (max 2048 caractères). Si non fournie, les clients seront redirigés vers la page post-achat Chariow par défaut.

Support multi-devises

Spécifiez la devise de paiement pour facturer les clients dans une devise différente de celle par défaut de votre boutique :
La réponse inclura les informations de taux de change lorsque la conversion de devise est appliquée.
  • Le code doit correspondre à une devise prise en charge par Chariow. Un code non pris en charge renvoie une erreur de validation 422 sur payment_currency au lieu de démarrer le paiement
  • Lorsque la devise de paiement diffère de la devise du produit, le prix est converti et une marge de conversion est ajoutée. Son taux dépend de la devise de paiement et c’est le même que celui appliqué aux prix affichés sur votre boutique : l’acheteur paie le montant qui lui a été présenté
  • Les montants de la vente (amount, original_amount) restent dans la devise du produit ; purchase.payment.amount est le montant payé par l’acheteur, dans la devise de paiement

Application de codes de réduction

Transmettez un code de réduction pour appliquer des économies :
La réponse affichera le montant réduit :

Champs personnalisés

Si votre produit a des champs personnalisés configurés, vous pouvez les collecter et les valider lors du paiement :
Les champs personnalisés doivent correspondre aux définitions de champs personnalisés configurées du produit. Les champs personnalisés invalides ou requis manquants entraîneront des erreurs de validation.

Suivi de campagne

Suivez la source des ventes en incluant un ID de campagne :
Cela vous aide à :
  • Suivre quelles campagnes marketing génèrent le plus de ventes
  • Attribuer les revenus à des canaux spécifiques
  • Analyser les performances des campagnes dans votre tableau de bord Chariow

Métadonnées personnalisées

Stockez des données personnalisées avec la vente pour vos propres besoins de suivi et d’intégration :

Notes importantes

  • Maximum 10 clés autorisées par vente
  • Chaque valeur est limitée à 255 caractères
  • Les clés doivent être des chaînes avec des caractères alphanumériques et des underscores
  • Les métadonnées personnalisées sont incluses dans les payloads webhook Pulse
Utilisez les métadonnées personnalisées pour lier les ventes Chariow à votre CRM, plateforme d’analyse ou systèmes internes. Les métadonnées sont retournées dans tous les webhooks liés aux ventes.

Adresse IP de l’acheteur

Le endpoint de paiement est appelé depuis votre serveur : l’adresse IP que nous observons est donc celle de votre infrastructure, pas celle de l’acheteur. Transmettez l’IP de l’acheteur dans customer_ip pour corriger cela :
Récupérez l’IP de l’acheteur depuis la requête qui arrive sur votre propre serveur, généralement la première valeur de l’en-tête X-Forwarded-For, ou CF-Connecting-IP si vous êtes derrière Cloudflare.

Ce que cela améliore

  • Moyens de paiement : le pays de l’acheteur est déterminé à partir de cette IP, et ce pays conditionne les moyens de paiement affichés sur la page de paiement
  • Analyses : les ventes sont attribuées au pays de l’acheteur plutôt qu’à la région d’hébergement de votre serveur
  • Contrôle des fraudes : la vente conserve la véritable IP de l’acheteur

Notes importantes

  • Le champ est facultatif. Sans lui, ou si l’IP ne peut pas être localisée, le pays de l’acheteur est déduit de phone.country_code, jamais de la localisation de votre serveur. La vente enregistre alors l’IP appelante comme adresse IP
  • Les formats IPv4 et IPv6 sont acceptés ; une valeur invalide renvoie une erreur 422
  • Le champ n’est pris en compte que sur les paiements via l’API, il ne peut donc pas être falsifié depuis un navigateur

Page de paiement dans une iframe

Pour afficher la page de paiement hébergée dans une iframe sur votre propre site, listez les origines qui l’intégreront dans embed_origins (4 au maximum) :
Chaque entrée doit être une origine HTTPS canonique : schéma https:// et hôte en minuscules, un port non standard facultatif, et ni chemin, ni paramètres de requête, ni fragment, ni identifiants, ni barre oblique finale. https://shop.example.com est valide ; https://shop.example.com/, http://shop.example.com et https://Shop.example.com sont refusées avec une erreur 422.

Achats cadeaux

Envoyez un objet gift pour acheter le produit pour quelqu’un d’autre. Le destinataire reçoit l’accès au produit, et l’acheteur paie :
Si le destinataire possède déjà le produit, l’API renvoie 409. La vente contient un objet gift avec le destinataire et le message.

Clients existants

Chaque boutique a un seul client par adresse e-mail, comparée sans tenir compte de la casse. Lorsqu’un paiement utilise l’e-mail d’un client existant, ce client est réutilisé et son prénom, son nom et son numéro de téléphone sont mis à jour avec les valeurs envoyées. Il en va de même pour le destinataire d’un cadeau.

Limites de débit

Le paiement dispose de son propre quota de 100 requêtes par minute et par clé API, distinct du reste de l’API publique : une synchronisation massive des ventes ou des produits ne peut pas empêcher vos acheteurs de payer. Au-delà, l’API renvoie 429 Too Many Requests.

Gestion des erreurs

Erreurs de paiement courantes et comment les gérer : Les erreurs liées aux règles métier (400, 404, 409) renvoient un message et un tableau errors vide. Les erreurs de validation (422 avec erreurs de champs) listent chaque champ invalide dans errors.

Exemple de réponse d’erreur

Vérifiez toujours l’objet errors pour les messages de validation spécifiques aux champs afin d’aider les utilisateurs à corriger leurs saisies.

Bonnes pratiques

Gérer tous les états de réponse

Vérifiez toujours le champ step et gérez tous les états possibles :

Utiliser les Pulses pour les mises à jour de vente

Ne vous fiez pas uniquement aux URL de redirection pour suivre la finalisation des ventes. Configurez les Pulses (webhooks) pour recevoir des notifications fiables :
  • Vente finalisée
  • Paiement reçu
  • Remboursement traité
Consultez le Guide des Pulses pour les instructions de configuration.

Valider avant le paiement

Réduisez les paiements échoués en validant les données avant d’appeler l’API :
  • Validation du format e-mail
  • Validation du format du numéro de téléphone
  • Vérifications des champs requis
  • Validation des champs personnalisés

Gérer les erreurs réseau

Implémentez une gestion appropriée des erreurs pour les problèmes réseau :

Stocker les ID de vente

Stockez toujours l’ID de vente retourné (purchase.id) pour :
  • Les demandes du service client
  • Le traitement des remboursements
  • La gestion des accès
  • Le suivi analytique

Tester avec différents scénarios

Testez votre intégration avec :
  • Des produits gratuits (finalisation immédiate)
  • Des produits payants (flux de paiement)
  • Des produits avec codes de réduction
  • Des produits avec champs personnalisés
  • Des produits qui exigent une adresse de livraison
  • Des produits à stock limité
  • Des ID de produit invalides
  • Des codes de réduction invalides

Prochaines étapes

Guide des ventes

Apprenez à récupérer et gérer les ventes

Pulses

Configurez les notifications pour les ventes finalisées

API Checkout

Consultez la référence complète de l’API Checkout