Événements de facturation — API/SDK avancé

Ce flux de vérification et de transmission des webhooks marchands concerne uniquement le mode API/SDK avancé. Vérifiez le webhook du prestataire de paiement sur votre serveur avant d’envoyer son événement de facturation à AffiHQ. N’envoyez pas d’événement de paiement depuis un retour du navigateur.

Avec Stripe automatique, AffiHQ reçoit, vérifie, contrôle le mode Stripe, retente et traite les livraisons natives Stripe Connect. Ne transmettez pas les mêmes événements Stripe depuis votre application et ne les dupliquez pas via l’API. En cas de problème de configuration native, consultez le guide de dépannage.

Paiement réussi

await affihq.billingEvents.send({
  type: 'payment.succeeded',
  provider: 'stripe',
  providerEventId: stripeEvent.id,
  customerId: merchantCustomerId,
  paymentId: invoice.id,
  billingCycle: 'monthly',
  currency: 'USD',
  amounts: {
    collectedMinor: 2500,
    taxMinor: 0,
    discountMinor: 500,
    commissionableMinor: 2000,
  },
  occurredAt: stripeEvent.createdAt,
})

Tous les montants utilisent l’unité mineure de la devise. commissionableMinor ne peut pas dépasser le montant encaissé hors taxes. Retirez les lignes non commissionnables avant l’envoi.

Remboursements et litiges

Envoyez les événements payment.refunded, payment.disputed et payment.dispute_resolved avec le paymentId d’origine. Avant paiement de l’affilié, la correction réduit la somme due. Après paiement, elle crée un solde négatif compensé par les futures commissions.

Événement reçu avant l’attribution

Un événement peut arriver avant l’attribution correspondante. AffiHQ le conserve comme non attribué puis relance la recherche lorsque l’attribution est verrouillée.

Idempotence

Le SDK envoie provider:providerEventId comme clé d’idempotence. Un rejeu identique est accepté comme doublon. Si AffiHQ renvoie idempotency_conflict, comparez les données financières avec l’événement d’origine avant tout nouvel envoi.