Provider events
The canonical billing events HyoNova maps every payment provider to, how FastSpring, Triple-A and Stripe events translate, and the billing timeline and notices they produce.
A payment method appears only after HyoNova has set up its payment provider.
Every provider speaks its own language. Each adapter translates provider notifications into a small set of canonical events, and the commerce core only ever handles those. Reconciliation produces the same events when it repairs a difference, so there is one path for every change.
Canonical events#
| Group | Events |
|---|---|
| Checkout | checkout.updated, checkout.completed, checkout.expired, checkout.failed |
| Order | order.completed, order.failed |
| Payment | payment.succeeded, payment.failed, payment.pending |
| Subscription | subscription.activated, subscription.updated, subscription.renewed, subscription.canceled, subscription.uncanceled, subscription.deactivated, subscription.past_due, subscription.paused, subscription.resumed |
| Refund | refund.succeeded, refund.failed |
| Settlement | settlement.reported |
| Other | ignored — recorded, changes nothing |
Each canonical event carries: an event id unique per provider, the time it happened, whether it is live, an optional provider sequence number for ordering, the HyoNova ids echoed back by the provider, and the relevant part — checkout, order, subscription snapshot, payment, refund or settlement. Amounts are integer minor units with their currency (Money handling). Card data is limited to brand, last four digits and expiry.
How providers map#
| Provider event | Canonical events |
|---|---|
FastSpring order.completed | order.completed, payment.succeeded, and subscription.activated when the order contains a subscription |
FastSpring order.failed | payment.failed |
FastSpring subscription.charge.completed / .failed | payment.succeeded + subscription.renewed, or payment.failed + subscription.past_due |
FastSpring subscription.payment.overdue | subscription.past_due |
FastSpring subscription.canceled | subscription.canceled (access continues to the period end) |
FastSpring subscription.deactivated | subscription.deactivated (access ends) |
FastSpring subscription.activated, .updated, .uncanceled, .paused, .resumed | The matching subscription event |
FastSpring return.created | refund.succeeded |
FastSpring payoutEntry.created | settlement.reported |
Triple-A payment good | payment.succeeded + checkout.completed |
Triple-A payment hold / short | checkout.updated (confirming / detected) |
Triple-A payment invalid | checkout.failed + payment.failed |
Stripe checkout.session.completed / .expired | checkout.completed (+ subscription.activated) / checkout.expired |
Stripe invoice.paid / invoice.payment_failed | payment.succeeded (+ subscription.renewed) / payment.failed |
Stripe customer.subscription.* | The matching subscription event |
Stripe refund.created / .updated | refund.succeeded or refund.failed once final |
Stripe payout.paid | settlement.reported |
| Anything else | ignored |
The billing timeline#
Applying an event writes an entry to the company's billing timeline. Each entry has a key that is unique per company, so a retried webhook or a second worker never writes it twice. Entries that concern the company's billing people also produce a notice — an in-app notification and an email in English or Arabic, sent once per event and recipient, only to members who can manage billing:
trial.ending, trial.ended, trial.extended, subscription.activated, subscription.renewed, subscription.recovered, subscription.plan_changed, subscription.change_scheduled, subscription.cancel_scheduled, subscription.canceled, subscription.resumed, subscription.past_due, subscription.restricted, subscription.paused, payment.succeeded, payment.failed, invoice.issued, invoice.due, invoice.overdue, invoice.paid, bank_payment.confirmed, refund.completed, credit.issued, renewal.upcoming.
Timeline entries without a notice include checkout.created, payment.detected, payment.overpaid, bank_proof.uploaded, subscription.updated and subscription.seats_changed.
Was this page helpful?
Thanks. Page ratings are not collected yet, so nothing was sent. If something is missing or wrong, see the Get help page.