Dépannage des paiements
Fonctionnalité en cours de déploiement. L'interface décrite ici est celle de la prochaine livraison : elle peut encore évoluer, et n'est pas forcément activée sur votre tenant.
À quoi ça sert
Cette page regroupe les réponses d'erreur de l'API de paiement et les situations où un paiement, une échéance ou un webhook ne se passe pas comme prévu.
Comment lire une erreur
Toutes les erreurs de l'API sont au format application/problem+json, par exemple :
{
"title": "Unprocessable Entity",
"status": 422,
"detail": "invalid cart",
"errors": [ { "field": "lines[0].unit_amount", "message": "must be a decimal string" } ]
}
errors[] désigne le champ fautif. Commencez toujours par là.
Par code de réponse
| Code | Signification | À vérifier |
|---|---|---|
400 | requête illisible (JSON invalide), ou Idempotency-Key manquante sur un débit ou un remboursement | le corps et les en-têtes |
401 | jeton absent, expiré ou illisible | redemander un jeton (client_credentials) |
403 | l'application du jeton n'est pas déclarée dans votre BillingAccount, le compte n'est pas prêt, le scope manque, ou le mode (one_time, subscription, usage) n'est pas autorisé | identity.applications, scopes, billingModes ; GET /v1/account |
404 | identifiant inconnu pour votre compte (les données d'un autre compte ne sont jamais visibles) | l'identifiant et son préfixe (cart_, cus_, sub_, pay_, chg_, inv_) |
409 | conflit d'état : panier déjà payé, abonnement déjà résilié, paiement déjà remboursé, PDF pas encore prêt, ou Idempotency-Key déjà utilisée avec un autre contenu | relire l'objet ; une clé par opération |
422 | valeur refusée : montant, devise, pays, adresse de retour non autorisée, durée de vie au-delà de carts.maxTTL… | errors[] |
503 | vos clés Stripe ou PayPal ne sont pas (encore) utilisables | GET /v1/account : loaded du fournisseur |
Votre compte n'est pas prêt
GET /v1/account répond ready: false, ou un fournisseur loaded: false :
- Le secret existe et contient les bonnes clés :
sng secret describe stripe-keys(secretKey,publishableKey) ousng secret describe paypal-keys(clientId,clientSecret). - Le
modecorrespond aux clés :testavec des clés de test,liveavec des clés de production. - Les clés ne sont pas révoquées dans votre tableau de bord Stripe ou PayPal.
- L'application de
identity.applicationsexiste (sng iam app list).
Vos clients ne peuvent pas payer
| Ce que voit votre client | Cause | Correction |
|---|---|---|
| « lien expiré » | panier ou lien au-delà de sa durée de vie | créer un nouveau panier ou un nouveau lien |
| Aucun moyen de paiement proposé | fournisseurs restreints par providers dans le panier, ou fournisseur non prêt | vérifier le panier et GET /v1/account |
| Carte refusée | refus de la banque ou de Stripe | le client essaie un autre moyen ; le détail est dans votre tableau de bord Stripe |
| Demande d'authentification à chaque débit | exigence de sa banque | transmettre action_url ; proposer PayPal |
Échéances et débits
| Situation | Ce qui se passe | À faire |
|---|---|---|
| Échéance d'abonnement refusée | subscription.past_due, nouvelles tentatives selon dunning.retryDelays | envoyer au client un lien de portail pour changer de moyen de paiement |
| Relances épuisées | subscription.unpaid ou subscription.canceled selon dunning.finalAction | relancer votre client ; recréer un abonnement si besoin |
Débit à l'usage requires_action ou failed | charge.action_required ou charge.failed, avec action_url | transmettre action_url au client |
| Débit en double craint après une relance de votre traitement | aucun si la même Idempotency-Key est réutilisée | une clé stable par client et par période |
Webhooks
Voir le tableau « Si ça ne marche pas » de la page Webhooks : signature invalide, horloge décalée, événements reçus plusieurs fois.
Ce qui n'est pas encore disponible
Ces demandes ne sont pas des erreurs de configuration : la fonctionnalité n'existe pas encore.
- Page de paiement sur votre propre domaine.
- Prélèvement SEPA.
- Plusieurs devises dans une même facture.
- Transmission des factures aux plateformes de dématérialisation (PDP).
Contacter le support
Si le problème persiste, contactez le support avec : l'heure de l'appel, la route, le code
de réponse, le detail de l'erreur et l'identifiant concerné (cart_…, pay_…, inv_…).
N'envoyez jamais vos clés Stripe ou PayPal ni votre secret de webhook.