L'endpoint /checkout n'est pas juste du code — c'est le moment où l'intention se transforme en chiffre d'affaires. Voici comment rédiger une documentation qui prévient les erreurs, sécurise les paiements et garantit une transaction fluide à chaque fois.
country est FR, siret est requis pour les transactions B2B »).order.created (intention) et order.paid (finalisation).GET /products qui échoue est une gêne. Un POST /checkout qui échoue, c'est une vente perdue, un client frustré et une réputation entachée.Dans l'architecture de toute plateforme e-commerce, l'endpoint checkout (souvent /v1/orders ou /v1/checkout) est l'« Endpoint Argent ».
Pour les développeurs frontend et les ingénieurs mobile qui intègrent votre API, la documentation checkout est le manuel du démineur. Un mauvais paramètre et tout explose (refus de paiement).
Ce guide couvre les composantes essentielles souvent absentes de la documentation API standard, pour que vos intégrateurs puissent construire un flux checkout robuste et à fort taux de conversion.
Avant même qu'un développeur regarde le body JSON, il doit connaître les règles d'engagement.
Le checkout ne se produit jamais dans le vide. Votre documentation doit clarifier :
POST /carts ?write:orders ou payments ?Note : Cet endpoint requiert un `cart_id` valide généré dans les 30 dernières minutes.
Le panier ne doit pas être vide. Les articles réservés sont libérés après 15 minutes d'inactivité.La documentation standard liste les champs. La grande documentation explique les relations.
Un payload checkout est complexe : données personnelles client, adresses de livraison, tokens de paiement. La principale source de friction est la logique conditionnelle.
Vous devez documenter explicitement les règles comme :
"750001" (6 chiffres) avec un message d'erreur clair.| Champ | Requis ? | Condition | Note France |
|---|---|---|---|
billing_address |
Conditionnel | Carte bancaire uniquement | Vérification AVS obligatoire |
siret |
Conditionnel | B2B France | 14 chiffres, validation Sirene API |
phone |
Conditionnel | Transporteurs express | Format E.164 : +33612345678 |
postal_code |
Toujours | — | 5 chiffres, pas d'espaces |
idempotency_key |
Recommandé | Toutes requêtes | UUID v4 généré côté client |
Un utilisateur dans le métro clique « Payer ». Le réseau coupe. L'app relance automatiquement. → Deux débits sur la carte.
Le serveur reconnaît la clé de la requête initiale et retourne la réponse originale. → Un seul débit, zéro confusion.
C'est le concept technique le plus critique pour les paiements, et il est pourtant souvent absent de la documentation.
Le Scénario : Un utilisateur mobile dans le métro clique sur « Payer ». Le train entre dans un tunnel. La requête est envoyée mais la réponse est perdue. L'app relance automatiquement.
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000Dans l'e-commerce moderne, le paiement n'est pas toujours instantané. En France particulièrement, des méthodes comme Klarna, le Virement SEPA, le Prélèvement SEPA ou le paiement en 3x/4x (Alma, Oney) prennent du temps.
Votre documentation doit préparer le développeur à l'état « en attente ».
| Type de réponse | Code HTTP | Statut commande | Exemple France |
|---|---|---|---|
| Synchrone | 200 OK / 201 Created |
paid |
Carte Visa/Mastercard approuvée |
| Asynchrone | 202 Accepted |
pending_payment |
Klarna, SEPA, Alma 3x, virement |
| Refusée | 402 Payment Required |
failed |
Fonds insuffisants, carte expirée |
Vos docs doivent renvoyer vers la section Webhooks. Expliquez que pour les méthodes asynchrones, la confirmation finale « Commande Payée » viendra via un événement webhook (payment.success), pas dans la réponse API immédiate. Si votre équipe oublie de documenter cela, les intégrateurs expédieront des commandes non encore payées.
Un 400 Bad Request ou 500 Server Error générique pendant le checkout est un cauchemar pour les équipes support. L'application client doit savoir exactement quoi dire à l'utilisateur.
Votre documentation nécessite une table de codes d'erreur dédiée au checkout :
| Code d'erreur | Message UI recommandé | Action recommandée |
|---|---|---|
inv_001 |
« Le produit SKU 123 est en rupture de stock. » | Retirer l'article du panier ou proposer un délai. |
pay_declined |
« Paiement refusé par votre banque. » | Inviter à essayer un autre moyen de paiement. |
addr_invalid |
« Le code postal ne correspond pas à la ville. » | Surligner le champ d'adresse en rouge. |
limit_exceeded |
« Quantité maximum dépassée pour ce produit. » | Ajuster automatiquement la quantité dans le panier. |
3ds_required |
« Authentification 3D Secure requise. » | Rediriger vers le flux 3DS de la banque. Obligatoire en Europe (DSP2). |
sepa_pending |
« Virement SEPA initié. Confirmation sous 1–3 jours ouvrés. » | Afficher un état « En attente » et envoyer un e-mail de confirmation. |
En Europe, la directive DSP2 (Strong Customer Authentication) rend l'authentification 3D Secure obligatoire pour la majorité des transactions en ligne. Votre documentation doit inclure un code d'erreur dédié (3ds_required) et expliquer le flux de redirection vers le portail bancaire. Les développeurs qui l'ignorent verront leurs transactions refusées massivement par les banques françaises.
Vous ne pouvez pas demander aux développeurs de tester le checkout avec de vraies cartes bancaires. Votre documentation doit inclure un « Guide de Test » avec des numéros magiques : une liste de numéros de carte de test qui déclenchent des comportements spécifiques (ex. : 4242 4242 4242 4242 pour Succès, 4000 0000 0000 0002 pour Refus, 4000 0025 0000 3155 pour 3DS). Distinguez clairement api.sandbox.votresite.com de api.votresite.com pour éviter que des commandes de test n'arrivent dans votre entrepôt.
Rédiger une documentation de qualité pour votre endpoint checkout n'est pas seulement une tâche technique — c'est une stratégie d'optimisation du chiffre d'affaires. Quand les développeurs comprennent exactement comment gérer les erreurs 409 Conflict ou les états 202 Accepted, ils construisent des interfaces utilisateur qui guident les clients à travers les frictions plutôt que de les bloquer.
Ne laissez pas une documentation vague devenir un goulot d'étranglement pour vos ventes.
Maîtrisez l'intégration API ShippyPro et optimisez votre expérience checkout :
Accédez à la documentation complète de l'API ShippyPro — endpoints, schémas, webhooks et codes d'erreur détaillés.
Consulter la doc →Boostez vos conversions avec des options de livraison flexibles et des points de retrait au checkout — intégration API ou plugin natif.
Découvrir →Automatisez la sélection du transporteur au moment du checkout et les workflows d'expédition sans développement supplémentaire.
Découvrir →401, 403, 404, 500 — le guide complet pour déboguer vos intégrations Adobe Commerce et éviter les interruptions de service.
Lire le guide →Explorez les 190+ transporteurs et canaux de vente connectables à ShippyPro via API ou intégration native.
Voir les intégrations →Guides techniques, analyses sectorielles et outils pour optimiser votre stack logistique e-commerce.
Explorer →La plupart des API modernes n'acceptent pas les numéros de carte bruts. Votre documentation doit expliquer que le frontend doit d'abord tokeniser la carte via un SDK de paiement (comme Stripe Elements, Adyen Web Components ou Payplug pour la France) et envoyer uniquement le payment_token (ex. : tok_123) à votre endpoint checkout. Cela maintient votre API hors du périmètre PCI DSS.
Documentez votre logique de « Race Condition ». En général, l'API doit retourner une erreur 409 Conflict identifiant exactement quel article n'est plus disponible, permettant au frontend de mettre à jour le panier immédiatement. Si plusieurs utilisateurs achètent simultanément le dernier article, le premier à confirmer le paiement l'emporte — les autres reçoivent un 409.
Généralement non. Une fois que /checkout retourne 201 Created, la commande est immuable pour le client. Les modifications nécessitent généralement un endpoint séparé /orders/{id}/cancel ou une intervention du service client. Documentez explicitement ce comportement pour éviter que les développeurs tentent des PUT sur une commande finalisée.
La DSP2 impose l'authentification forte (SCA) pour la quasi-totalité des paiements en ligne en Europe. Votre flow checkout doit prévoir une étape de redirection 3DS : après le POST /checkout, si le serveur retourne 3ds_required avec une redirect_url, le frontend redirige l'utilisateur vers le portail de sa banque. Après authentification, la banque renvoie l'utilisateur vers votre return_url avec un token de confirmation que vous soumettez via POST /checkout/confirm.
Récupérez vos clés API et accédez à la documentation complète de ShippyPro — endpoints, webhooks, sandbox et exemples de code pour démarrer en minutes.
Créez votre compte gratuit et commencez à builder →