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 :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 client2
Traiter la réponse
Vérifiez le champ
step dans la réponse :- payment : Redirigez le client vers
checkout_urlpour 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 objetshipping 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 champstep indiquant l’état actuel :
En attente de paiement
Pour les produits payants, vous recevrez une URL de paiement :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 :Déjà acheté
Si le client possède déjà le produit :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 :- Le code doit correspondre à une devise prise en charge par Chariow. Un code non pris en charge renvoie une erreur de validation
422surpayment_currencyau 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.amountest 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 :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 :- 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
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 danscustomer_ip pour corriger cela :
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 dansembed_origins (4 au maximum) :
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 objetgift 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 renvoie429 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
Bonnes pratiques
Gérer tous les états de réponse
Vérifiez toujours le champstep 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é
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