Gateway event catalog
All 36 documented transaction, check, recurring, settlement, chargeback and card-updater event names, with payload guidance.
Route by the exact event type
Every gateway notification uses event_id, event_type and event_body. The catalog below lists all 36 event names published in the reviewed gateway event pages. Event-body samples are examples, not a single uniform schema; optional fields, empty values and types vary by event family. Envelope field Purpose event_id Unique notification identifier; use for duplicate handling. event_type Exact routing string from the catalog below. event_body Family-specific merchant, resource and outcome details.
Transaction outcomes
Each action has success, failure and unknown variants. These describe the action outcome; settlement status is separate. Samples include transaction_id, transaction_type, condition, processor_id, currency and an action object with amount, response_code and response_text. Card and check details differ; transaction_type examples include cc, ck and cs. event_type Meaning transaction.sale.success Action accepted successfully transaction.sale.failure Action failed transaction.sale.unknown Outcome unresolved transaction.auth.success Action accepted successfully transaction.auth.failure Action failed transaction.auth.unknown Outcome unresolved transaction.capture.success Action accepted successfully transaction.capture.failure Action failed transaction.capture.unknown Outcome unresolved transaction.void.success Action accepted successfully transaction.void.failure Action failed transaction.void.unknown Outcome unresolved transaction.refund.success Action accepted successfully transaction.refund.failure Action failed transaction.refund.unknown Outcome unresolved transaction.credit.success Action accepted successfully transaction.credit.failure Action failed transaction.credit.unknown Outcome unresolved transaction.validate.success Action accepted successfully transaction.validate.failure Action failed transaction.validate.unknown Outcome unresolved
Check settlement and returns
These events track subsequent ACH/check status. Samples include transaction_id, condition, check information and action details. Preserve a return or late-return workflow even after an earlier successful payment notification. event_type Meaning transaction.check.status.settle Check settled transaction.check.status.return Check returned transaction.check.status.latereturn Check returned after initial settlement
Recurring plans and subscriptions
Plan events concern configuration. Subscription events concern a recurring schedule and can include subscription_id, next_charge_date, completed_payments, attempted_payments, remaining_payments and plan. They do not by themselves prove that a scheduled charge succeeded; process transaction outcomes separately. event_type Meaning recurring.plan.add Record created recurring.plan.update Record changed recurring.plan.delete Record removed or canceled recurring.subscription.add Record created recurring.subscription.update Record changed recurring.subscription.delete Record removed or canceled
Settlement batches
The completion sample includes batch_id, count, amount, merchant, processor, by_card_type and transaction_ids. The failure sample contains batch_id, merchant and processor, so do not require the completion totals on every event. event_type Meaning settlement.batch.complete Batch completed settlement.batch.failure Action failed
Chargeback batches
Chargeback reporting depends on processor support. The documented payload groups chargebacks under merchant and processor with count, chargeback_amount and chargebacks entries containing id, date, masked card number, amount and reason. Route it into a dispute workflow; do not interpret it as a normal refund. event_type Meaning chargeback.batch.complete Batch completed
Automatic Card Updater summaries
These summaries distinguish records updated automatically, records requiring customer contact and closed accounts. Payload examples include updated_date, merchant and cards_checked, with separate vault and recurring update lists. Use customer_vault_id plus billing_id for vault records and subscription_id for recurring records; do not equate an updater result with a successful payment. event_type Meaning acu.summary.automaticallyupdated Card records updated acu.summary.contactcustomer Customer follow-up required acu.summary.closedaccount Account reported closed
Account for sample differences
The published recurring samples show plan fields nested under plan for one event and directly in event_body for others. Some recurring and ACU examples also contain JSON punctuation errors, and fields such as counts or merchant IDs vary between numbers and strings. These examples should not be copied into a strict universal schema. Create family-specific parsers and validate against real test-account deliveries before enforcing exact field types. Do not assume every family includes features.is_test_mode; bind the receiver to known environment configuration. Preserve identifiers losslessly and handle monetary strings with decimal-safe arithmetic. Keep raw payload access restricted; examples include customer contact data even when card or account numbers are masked.
Use the right event system
This catalog covers gateway Webhooks events. Merchant Sign-Up application and merchant-lifecycle events belong to the separate subscription API and signature contract. Neither system establishes a Betterpay-specific payment.succeeded event name. Registration and processing Verify gateway payloads Merchant Sign-Up webhooks