Skip to main content
  • Send to AI

IPNs

Each payment gateway sends webhook notifications to Farfalla when payment state changes. All gateways share a single IPN controller, exposed at two routes:

  • payment/ipn/{gateway_type} (web, named receivePaymentEvents): used by MercadoPago, Stripe, and Yuno.
  • ipn/{gateway_type} (API, named receivePaymentEventsApi, under /api/v1): used by PayU.

From there, a gateway-specific event manager routes the payload to the appropriate handler.

Deduplication and recovery​

Every accepted IPN is recorded as a row in the IPN records table keyed by (gateway_type, ipn_id). Repeated deliveries with the same ipn_id are detected and short-circuited with a 200 OK, so the gateway considers the IPN delivered and the handler runs at most once for that id.

If the handler errors out, the record remains marked unprocessed. The ProcessPendingIpns job (scheduled every 5 minutes) reprocesses these records. That is the recovery path for transient handler failures; see Payment Synchronization.

Stripe​

URL: https://{tenant_domain}/payment/ipn/stripe

Configure in the Stripe dashboard under Webhooks. Events to subscribe:

  • charge.succeeded
  • charge.refunded
  • charge.failed
  • charge.pending
  • charge.expired
  • charge.captured
  • charge.updated
  • charge.dispute.created
  • charge.dispute.updated
  • charge.dispute.closed
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
  • customer.subscription.trial_will_end
  • invoice.payment_succeeded
  • invoice.payment_failed
  • invoice.updated
  • checkout.session.completed

Stripe currently handles 5 event type groups: charge, customer.subscription, dispute, invoice, and checkout.session. Each routes to a dedicated handler.

MercadoPago​

URL: https://{tenant_domain}/payment/ipn/mercadopago

Configure at https://www.mercadopago.com.ar/developers/panel/notifications/ipn for third-party owned accounts.

Routed events:

  • payment
  • authorized_payment
  • merchant_order
  • subscription_preapproval (routes to the subscription handler)
  • preapproval (routes to the subscription handler)

subscription_preapproval and preapproval are two independent topics that both resolve to the same subscription handler. Both must be subscribed in the MercadoPago dashboard.

Short-circuited at the controller​

preapproval_plan events are not routed through the event manager. The IPN controller returns HTTP/1.1 200 OK directly for preapproval_plan topics before the event manager is instantiated. No handler exists for preapproval_plan.

Yuno​

URL: https://{tenant_domain}/payment/ipn/yuno

The Yuno event manager reads the routing field from the payload as type_event first, then falls back to type, and finally defaults to payment when neither is present. Production payloads use type_event; the type fallback covers older or alternate payload shapes.

Payment events:

  • payment.purchase
  • payment.authorize
  • payment.capture
  • payment.refund
  • payment.cancel
  • payment.verify
  • payment.chargeback
  • payment.fraud_screening

Subscription events:

  • subscription.create
  • subscription.pause
  • subscription.resume
  • subscription.active
  • subscription.cancel
  • subscription.complete
X

Graph View