Remboursements et avoirs

Bêta

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

Rembourser un client, en totalité ou en partie. Le remboursement passe par le fournisseur qui a encaissé (Stripe ou PayPal), depuis votre compte, et la plateforme émet l'avoir qui corrige la facture d'origine.

Prérequis

Un jeton avec le scope refunds.
L'identifiant du paiement (pay_…) : dans le webhook payment.succeeded, dans le panier payé (payment_id), ou par GET /v1/payments?customer_id=….

1. Rembourser

curl -s -X POST https://billing-api.dev.stackngo.fr/v1/refunds \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-10042-1" \
  -d '{ "payment_id": "pay_01J9ZQ8T…", "amount": "18.00", "reason": "Support de cours non livré" }'

Champ	Rôle
`payment_id`	le paiement à rembourser
`amount`	montant TTC à rembourser ; sans `amount`, remboursement total du reste à rembourser
`reason`	motif (500 caractères au plus), repris sur l'avoir

Idempotency-Key est obligatoire : un remboursement relancé avec la même clé n'est pas exécuté deux fois.

Ce que vous obtenez

{
  "id": "ref_01J9ZT4F5G6H7J8K9L0M",
  "payment_id": "pay_01J9ZQ8T…",
  "status": "pending",
  "amount": "18.00",
  "currency": "EUR",
  "reason": "Support de cours non livré",
  "created_at": "2026-10-10T09:00:00Z"
}

Quand le fournisseur confirme, vous recevez refund.succeeded ; le remboursement porte alors credit_note_id, l'avoir émis. Le paiement passe partially_refunded ou refunded, et amount_refunded cumule les remboursements.

L'avoir se lit comme une facture :

curl -s "https://billing-api.dev.stackngo.fr/v1/invoices?customer_id=cus_01J9ZR1A2B3C4D5E6F7G&kind=credit_note" \
  -H "Authorization: Bearer $TOKEN"

Il porte kind: "credit_note", son propre numéro et corrects_invoice_id, la facture qu'il corrige. Son PDF Factur-X se télécharge comme une facture.

Ce que vous pouvez en attendre

Un avoir par remboursement réussi, numéroté dans sa propre série, sans trou.
La facture d'origine n'est jamais modifiée : c'est l'avoir qui la corrige.
Plusieurs remboursements partiels sont possibles, jusqu'au montant du paiement.
Le délai pour que l'argent revienne sur le compte de votre client est celui de Stripe ou PayPal.
Les remboursements apparaissent dans la colonne refunded du rapport d'encaissement.

Si ça ne marche pas

Ce que vous voyez	Cause	Correction
`422` sur `amount`	montant supérieur au reste à rembourser, ou non décimal	vérifier `amount` et `amount_refunded` du paiement
`409`	paiement déjà totalement remboursé, ou même `Idempotency-Key` avec un autre contenu	relire le paiement ; une clé par remboursement
`refund.failed`	le fournisseur a refusé (solde insuffisant sur votre compte, paiement trop ancien…)	voir le détail dans votre tableau de bord Stripe ou PayPal, puis réessayer avec une nouvelle clé
`403`	scope `refunds` manquant	l'ajouter à l'application dans le `BillingAccount`

Voir aussi Dépannage des paiements.

À quoi ça sert​

Prérequis​

1. Rembourser​

Ce que vous obtenez​

Ce que vous pouvez en attendre​

Si ça ne marche pas​

Voir aussi​