Event Flow

All inter-service communication happens through NATS JetStream. This page documents every event type, its subject, and which services produce and consume it.

JetStream Configuration

nats CLI

# Stream: payments
# Subjects: payments.>
# Retention: limits (max messages or max age)
# Storage: file (persisted to disk)
# Replicas: 1 (single-node)
# Max age: 72h (3 days)
# Max bytes: 1GB

nats stream add payments \
  --subjects "payments.>" \
  --retention limits \
  --max-msgs 100000 \
  --max-age 72h \
  --max-bytes 1GB \
  --storage file \
  --replicas 1 \
  --defaults

Event Types

Payment Events

payments.payment_intent.created

Fired when a new payment intent is created. The payment has not yet been processed.

Producer: HyperswitchConsumers: Tazama, NATS-KB Bridge

payments.payment_intent.succeeded

Fired when a payment succeeds. The connector has authorized the transaction.

Producer: HyperswitchConsumers: NATS-KB Bridge, Webhooks

payments.payment_intent.failed

Fired when a payment fails. Includes the connector error code and message.

Producer: HyperswitchConsumers: NATS-KB Bridge, Webhooks

payments.payment_intent.processing

Fired when a payment is sent to the connector for processing. Used for async payment methods.

Producer: HyperswitchConsumers: Webhooks

payments.refund.created

Fired when a refund is initiated. Includes the refund amount and reason.

Producer: HyperswitchConsumers: Tazama, Webhooks

payments.refund.succeeded

Fired when the refund is confirmed by the connector.

Producer: HyperswitchConsumers: Webhooks

Fraud Events

fraud_alerts.alert.triggered

Fired when Tazama flags a transaction. Contains the risk score, triggered rules, and recommended action.

Producer: TazamaConsumers: Webhooks

fraud_alerts.alert.resolved

Fired when a fraud alert is manually resolved by an admin.

Producer: TazamaConsumers: Webhooks

Event Schema

All events follow a consistent envelope format:

JSON

{
  "event_id": "evt_abc123",
  "event_type": "payments.payment_intent.succeeded",
  "timestamp": "2026-07-26T10:30:00Z",
  "data": {
    "payment_id": "pay_xyz789",
    "amount": 100000,
    "currency": "NGN",
    "status": "Succeeded",
    "connector": "paystack",
    "customer_id": "cus_abc123",
    "metadata": {
      "order_id": "order_456"
    }
  },
  "metadata": {
    "service": "hyperswitch",
    "version": "1.0.0"
  }
}

Subscribing to Events

To receive events in your application, you can either:

Option 1: Webhooks (Recommended)

Configure a webhook endpoint in the dashboard. OpenPay delivers events via HTTP POST to your URL with retry logic.

Webhook Guide →

Option 2: NATS Consumer

Connect directly to NATS from your application for real-time event streaming with exactly-once delivery.

nats-cli sub payments.>