Paiement à l'usage

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

Quand le montant change chaque mois (consommation, heures, volume), votre client enregistre une fois son moyen de paiement ; ensuite, votre application envoie chaque mois le panier de sa consommation et la plateforme le débite aussitôt, puis émet la facture.

Prérequis

• usage dans billingModes de votre compte de paiement.
• Un jeton avec le scope charges.

1. Enregistrer le client

curl -s -X PUT https://billing-api.dev.stackngo.fr/v1/customers \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "external_ref": "user-381",
    "name": "Dupont Conseil",
    "email": "compta@dupont.example",
    "vat_number": "FR40552100554",
    "address": { "line1": "3 place Bellecour", "postal_code": "69002", "city": "Lyon", "country": "FR" }
  }'

{ "id": "cus_01J9ZR1A2B3C4D5E6F7G", "external_ref": "user-381", "name": "Dupont Conseil", "has_payment_method": false, "created_at": "2026-10-08T10:30:00Z", "…": "…" }

PUT /v1/customers crée le client, ou le met à jour s'il existe déjà avec ce external_ref.

2. Faire enregistrer son moyen de paiement

curl -s -X POST https://billing-api.dev.stackngo.fr/v1/customers/cus_01J9ZR1A2B3C4D5E6F7G/setup-links \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "provider": "stripe", "return_url": "https://shop.acme.example/compte", "ttl_seconds": 86400 }'

{ "url": "https://pay.dev.stackngo.fr/acme/…", "expires_at": "2026-10-09T10:31:00Z" }

Envoyez ce lien à votre client. Il y enregistre sa carte (ou son compte PayPal avec "provider": "paypal") sans rien payer. Ensuite, GET /v1/customers/{id} répond "has_payment_method": true.

3. Débiter le panier du mois

curl -s -X POST https://billing-api.dev.stackngo.fr/v1/customers/cus_01J9ZR1A2B3C4D5E6F7G/charges \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: usage:user-381:2026-10" \
  -d '{
    "currency": "EUR",
    "period_start": "2026-10-01",
    "period_end": "2026-10-31",
    "lines": [
      { "label": "Appels API", "quantity": "182000", "unit_amount": "0.0004", "tax_category": "S", "tax_rate": "20.00" },
      { "label": "Stockage", "quantity": "37", "unit_code": "E34", "unit_amount": "0.10", "tax_category": "S", "tax_rate": "20.00" }
    ],
    "tags": { "shop": "api", "period": "2026-10" }
  }'

Idempotency-Key est obligatoire : prenez une clé qui identifie le client et la période (usage:<client>:<mois>). Si votre traitement mensuel est relancé, le même appel renvoie le même débit au lieu de débiter deux fois.

Ce que vous obtenez

{
  "id": "chg_01J9ZS3C4D5E6F7G8H9J",
  "customer_id": "cus_01J9ZR1A2B3C4D5E6F7G",
  "status": "succeeded",
  "currency": "EUR",
  "totals": { "subtotal": "76.50", "tax": "15.30", "total": "91.80", "taxes": [ { "category": "S", "rate": "20.00", "basis": "76.50", "amount": "15.30" } ] },
  "payment_id": "pay_01J9ZS3D…",
  "invoice_id": "inv_01J9ZS3E…",
  "created_at": "2026-11-01T06:00:00Z",
  "tags": { "shop": "api", "period": "2026-10" }
}

status	Signification	À faire
succeeded	débité, facture émise	rien
processing	en cours de confirmation	attendre charge.succeeded ou charge.failed
requires_action	la banque exige une authentification forte de votre client	lui transmettre action_url
failed	refusé (failure_code)	lui transmettre action_url ; la plateforme retente à next_retry_at

Ce que vous pouvez en attendre

• Jamais de double débit pour une même Idempotency-Key. Réutiliser une clé avec un autre contenu est refusé (409).
• Le débit est immédiat, sans que votre client ait à intervenir, tant que sa banque l'accepte.
• En cas d'authentification forte ou de refus, action_url mène votre client vers une page de paiement à vos couleurs pour régler ce débit ; vous recevez charge.action_required ou charge.failed, et les nouvelles tentatives suivent dunning de votre compte.
• Une facture par débit réussi, avec la période (period_start, period_end) indiquée.

Si ça ne marche pas

Ce que vous voyez	Cause	Correction
Débit refusé faute d'Idempotency-Key	en-tête obligatoire sur ce débit	l'ajouter
409	même Idempotency-Key avec un autre contenu	une clé par client et par période
Débit refusé, has_payment_method: false sur le client	le client n'a pas encore enregistré son moyen de paiement	lui renvoyer un lien d'enregistrement
requires_action à chaque mois	la banque du client demande toujours une authentification	transmettre action_url ; proposer PayPal
Lien d'enregistrement expiré	ttl_seconds dépassé	en créer un nouveau

Voir aussi Dépannage des paiements.

Voir aussi

• Abonnements
• Factures
• Webhooks