Saga Pattern — Choreography

Event-driven saga without a coordinator

In choreography, there is no central saga DB. The debit service publishes TransferDebited; the credit service consumes it and publishes TransferCredited or CreditFailed; the debit service listens for CreditFailed and publishes DebitCompensated.

ShardPay's refund flow works this way: RefundRequested → billing validates → RefundApproved → ledger credits merchant → RefundCompleted → notification emails the merchant. Each handler is idempotent on refundId.

When ShardPay chooses choreography

Choreography fits when the flow is short (≤4 steps), teams own services independently, and event contracts are stable. ShardPay's refund saga has three services with infrequent schema changes — a good fit.

Refund walkthrough

1. Merchant API publishes RefundRequested{refundId, merchantId, amount} to shardpay.refunds.v1.
2. Billing service consumes, validates merchant balance, publishes RefundApproved{refundId}.
3. Ledger service consumes, credits merchant account idempotently, publishes RefundCompleted{refundId}.
4. Notification service consumes, sends email — no compensation needed (at-most-once email is acceptable).

If ledger credit fails, it publishes RefundFailed{refundId, reason}. Billing listens and publishes RefundApprovalRevoked — no central orchestrator coordinates the rollback.

// ShardPay refund choreography — ledger handler
@KafkaListener(topics = "shardpay.refunds.approved.v1")
public void onRefundApproved(ConsumerRecord<String, RefundApproved> record) {
    RefundApproved event = record.value();
    if (processedEvents.exists(event.refundId())) return;

    try {
        ledgerService.creditMerchant(event.merchantId(), event.amountCents());
        kafkaTemplate.send("shardpay.refunds.completed.v1",
            event.refundId(), RefundCompleted.from(event));
        processedEvents.mark(event.refundId());
    } catch (InsufficientFundsException e) {
        kafkaTemplate.send("shardpay.refunds.failed.v1",
            event.refundId(), RefundFailed.from(event, e.getMessage()));
    }
}

Choreography vs orchestration

ShardPay uses both deliberately. The decision matrix below is documented in their architecture decision records (ADRs).

Pitfalls in choreography

Missing compensation listener — if debit service does not subscribe to CreditFailed, a failed credit leaves a orphaned debit. ShardPay's CI checks that every forward event type has a documented compensation path in the event catalog.

Cyclic dependencies — service A waits for B's event while B waits for A's. ShardPay's refund chain is strictly acyclic: Requested → Approved → Completed.