Paiement

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.

Les produits à prix libre 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 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 :

Type de produit	Achat répété	Comportement
Service	Toujours autorisé	Les clients peuvent acheter des produits de service un nombre illimité de fois. Idéal pour les consultations, adhésions ou services récurrents.
Licence	Toujours autorisé	Les clients peuvent acheter des produits licence plusieurs fois. Chaque achat génère une nouvelle clé de licence unique.
Téléchargeable	Bloqué	Retourne `already_purchased` si le client a un accès actif.
Cours	Bloqué	Retourne `already_purchased` si le client a un accès actif.
Bundle	Bloqué	Retourne `already_purchased` si le client a un accès actif.

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.

Initier le paiement

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

Traiter la réponse

Vérifiez le champ step dans la réponse :

awaiting_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

Traiter le paiement

Le client finalise le paiement sur la page de paiement sécurisée Chariow

Recevoir le webhook

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

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 tous les types de produits Chariow :

Produits téléchargeables : Fichiers numériques (PDF, logiciels, médias)
Services : Consultation, adhésions, abonnements
Cours : Contenu éducatif avec leçons et chapitres
Licences : Clés de licence logicielle avec gestion des activations
Bundles : Collections de plusieurs produits

Tous les types de produits sauf la tarification à prix libre sont pris en charge via l’API publique.

Initier un paiement

Créez une nouvelle session de paiement :

curl -X POST "https://api.chariow.com/v1/checkout" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_abc123",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": {
      "number": "1234567890",
      "country_code": "US"
    },
    "discount_code": "SAVE20"
  }'

Paramètres de la requête

Paramètre	Type	Requis	Description
`product_id`	string	Oui	ID public ou slug du produit (par ex., `prd_abc123xyz` ou `premium-course`)
`email`	string	Oui	Adresse e-mail du client (max 255 caractères)
`first_name`	string	Oui	Prénom du client (max 50 caractères)
`last_name`	string	Oui	Nom de famille du client (max 50 caractères)
`phone.number`	string	Oui	Numéro de téléphone (numérique uniquement)
`phone.country_code`	string	Oui	Code pays ISO (par ex., “US”, “FR”, “GB”)
`discount_code`	string	Non	Code de réduction à appliquer (max 100 caractères)
`campaign_id`	string	Non	ID public de campagne ou code de suivi
`custom_fields`	object	Non	Valeurs de champs personnalisés (paires clé-valeur)
`payment_currency`	string	Non	Code de devise (ISO 4217, par ex., “USD”, “EUR”)
`redirect_url`	string	Non	URL de redirection personnalisée après finalisation du paiement (max 2048 caractères)
`custom_metadata`	object	Non	Métadonnées personnalisées clé-valeur à stocker avec la vente (max 10 clés, 255 caractères par valeur). Inclus dans les payloads webhook Pulse.

Champs d’adresse de livraison

Lorsque le produit a l’option “Exiger une adresse de livraison” activée, vous devez inclure les champs d’adresse de livraison dans votre requête de paiement :

Paramètre	Type	Requis	Description
`address`	string	Conditionnel	Adresse postale pour la livraison (max 255 caractères)
`city`	string	Conditionnel	Ville pour la livraison (max 100 caractères)
`state`	string	Conditionnel	État ou région pour la livraison (max 100 caractères)
`country`	string	Conditionnel	Code pays (ISO 3166-1 alpha-2, par ex., “US”, “FR”)
`zip`	string	Conditionnel	Code postal pour la livraison (max 20 caractères)

Ces champs sont requis uniquement lorsque le produit a la livraison activée. Si la livraison n’est pas requise, ces champs sont ignorés.

Exemple avec adresse de livraison

{
  "product_id": "prd_abc123xyz",
  "email": "[email protected]",
  "first_name": "Jean",
  "last_name": "Dupont",
  "phone": {
    "number": "0612345678",
    "country_code": "FR"
  },
  "address": "123 Rue Principale",
  "city": "Paris",
  "state": "Île-de-France",
  "country": "FR",
  "zip": "75001"
}

É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 :

{
  "data": {
    "step": "awaiting_payment",
    "message": null,
    "purchase": {
      "id": "sal_xyz789",
      "status": "awaiting_payment",
      "amount": {
        "amount": 7920,
        "currency": "USD"
      }
    },
    "payment": {
      "checkout_url": "https://payment.chariow.com/checkout?token=abc123",
      "transaction_id": "txn_def456"
    }
  }
}

Redirigez le client vers checkout_url pour finaliser son paiement.

Finalisé (produits gratuits)

Pour les produits gratuits, la vente est finalisée immédiatement :

{
  "data": {
    "step": "completed",
    "message": null,
    "purchase": {
      "id": "sal_xyz789",
      "status": "completed"
    },
    "payment": {
      "checkout_url": null,
      "transaction_id": null
    }
  }
}

Déjà acheté

Si le client possède déjà le produit :

{
  "data": {
    "step": "already_purchased",
    "message": "You have already purchased this product",
    "purchase": null,
    "payment": null
  }
}

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 :

curl -X POST "https://api.chariow.com/v1/checkout" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_abc123xyz",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": {
      "number": "1234567890",
      "country_code": "US"
    },
    "redirect_url": "https://yoursite.com/thank-you?sale={sale_id}"
  }'

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 :

{
  "product_id": "prd_abc123xyz",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "payment_currency": "EUR"
}

La réponse inclura les informations de taux de change lorsque la conversion de devise est appliquée.

Application de codes de réduction

Transmettez un code de réduction pour appliquer des économies :

{
  "product_id": "prd_abc123xyz",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "discount_code": "SAVE20"
}

La réponse affichera le montant réduit :

{
  "data": {
    "purchase": {
      "original_amount": {
        "amount": 9900,
        "currency": "USD",
        "formatted": "$99.00"
      },
      "amount": {
        "amount": 7920,
        "currency": "USD",
        "formatted": "$79.20"
      },
      "discount_amount": {
        "amount": 1980,
        "currency": "USD",
        "formatted": "$19.80"
      },
      "discount": {
        "id": "dis_xyz789",
        "code": "SAVE20",
        "type": "percentage",
        "value": 20
      }
    }
  }
}

Champs personnalisés

Si votre produit a des champs personnalisés configurés, vous pouvez les collecter et les valider lors du paiement :

{
  "product_id": "prd_abc123xyz",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "custom_fields": {
    "company_name": "Acme Corp",
    "job_title": "Developer",
    "team_size": "10-50"
  }
}

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 :

{
  "product_id": "prd_abc123xyz",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "campaign_id": "camp_summer2024"
}

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 :

{
  "product_id": "prd_abc123xyz",
  "email": "[email protected]",
  "first_name": "Jean",
  "last_name": "Dupont",
  "phone": {
    "number": "0612345678",
    "country_code": "FR"
  },
  "custom_metadata": {
    "order_ref": "ORD-123",
    "source": "landing_page",
    "utm_campaign": "summer_sale"
  }
}

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.

Gestion des erreurs

Erreurs de paiement courantes et comment les gérer :

Statut HTTP	Erreur	Cause	Solution
401	Non autorisé	Clé API invalide ou manquante	Vérifiez que votre clé API est correcte et incluse dans l’en-tête `Authorization`
404	Produit non trouvé	ID de produit invalide ou produit non publié	Vérifiez que l’ID/slug du produit existe et est publié
422	Échec de validation	Champs requis manquants ou invalides	Vérifiez que tous les champs requis sont fournis avec les formats corrects
422	Prix libre non pris en charge	Le produit utilise la tarification à prix libre	Redirigez les clients vers votre boutique Chariow ou utilisez le widget Snap
422	Code de réduction invalide	Code de réduction expiré, invalide ou déjà utilisé	Vérifiez que le code de réduction est actif et applicable
422	Adresse de livraison manquante	Le produit requiert une livraison mais les champs d’adresse sont manquants	Incluez les champs `address`, `city`, `state`, `country` et `zip`

Exemple de réponse d’erreur

{
  "message": "The email field must be a valid email address.",
  "data": [],
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ],
    "phone.number": [
      "The phone.number field is required."
    ]
  }
}

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 :

const response = await fetch('https://api.chariow.com/v1/checkout', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(checkoutData)
});

const result = await response.json();

switch (result.data.step) {
  case 'awaiting_payment':
    // Rediriger vers l'URL de paiement
    window.location.href = result.data.payment.checkout_url;
    break;

  case 'completed':
    // Afficher le message de succès pour les produits gratuits
    showSuccessMessage(result.data.purchase);
    break;

  case 'already_purchased':
    // Informer le client qu'il possède déjà ce produit
    showAlreadyPurchasedMessage(result.data.message);
    break;
}

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 :

try {
  const response = await fetch('https://api.chariow.com/v1/checkout', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(checkoutData)
  });

  if (!response.ok) {
    const error = await response.json();
    handleCheckoutError(error);
    return;
  }

  const data = await response.json();
  handleCheckoutSuccess(data);

} catch (error) {
  // Gérer les erreurs réseau
  console.error('Checkout failed:', error);
  showErrorMessage('Impossible de traiter le paiement. Veuillez réessayer.');
}

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

Introduction

Guides

Resources

Intégration MCP

Achats répétés

Aperçu du flux de paiement

Types de produits pris en charge

Initier un paiement

Paramètres de la requête

Champs d’adresse de livraison

Exemple avec adresse de livraison

États de réponse du paiement

En attente de paiement

Finalisé (produits gratuits)

Déjà acheté

URL de redirection personnalisées

Support multi-devises

Application de codes de réduction

Champs personnalisés

Suivi de campagne

Métadonnées personnalisées

Notes importantes

Gestion des erreurs

Exemple de réponse d’erreur

Bonnes pratiques

Gérer tous les états de réponse

Utiliser les Pulses pour les mises à jour de vente

Valider avant le paiement

Gérer les erreurs réseau

Stocker les ID de vente

Tester avec différents scénarios

Prochaines étapes

Guide des ventes

Pulses

API Checkout

Introduction

Guides

Resources

Intégration MCP

​Achats répétés

​Aperçu du flux de paiement

​Types de produits pris en charge

​Initier un paiement

​Paramètres de la requête

​Champs d’adresse de livraison

​Exemple avec adresse de livraison

​États de réponse du paiement

​En attente de paiement

​Finalisé (produits gratuits)

​Déjà acheté

​URL de redirection personnalisées

​Support multi-devises

​Application de codes de réduction

​Champs personnalisés

​Suivi de campagne

​Métadonnées personnalisées

​Notes importantes

​Gestion des erreurs

​Exemple de réponse d’erreur

​Bonnes pratiques

​Gérer tous les états de réponse

​Utiliser les Pulses pour les mises à jour de vente

​Valider avant le paiement

​Gérer les erreurs réseau

​Stocker les ID de vente

​Tester avec différents scénarios

​Prochaines étapes

Guide des ventes

Pulses

API Checkout

Achats répétés

Aperçu du flux de paiement

Types de produits pris en charge

Initier un paiement

Paramètres de la requête

Champs d’adresse de livraison

Exemple avec adresse de livraison

États de réponse du paiement

En attente de paiement

Finalisé (produits gratuits)

Déjà acheté

URL de redirection personnalisées

Support multi-devises

Application de codes de réduction

Champs personnalisés

Suivi de campagne

Métadonnées personnalisées

Notes importantes

Gestion des erreurs

Exemple de réponse d’erreur

Bonnes pratiques

Gérer tous les états de réponse

Utiliser les Pulses pour les mises à jour de vente

Valider avant le paiement

Gérer les erreurs réseau

Stocker les ID de vente

Tester avec différents scénarios

Prochaines étapes