Finishing a Payments Flow in NestJS: Events, Config, and the Limits of Pre-Checks

I'm building RunHop in public, a social + event platform for running races. Today was a cleanup-and-integration day for the payments module.

The core problem wasn't creating payments. That part already existed. The real work was making payment review actually affect the rest of the system in a clean way.

The Product-Level Rule

There are two different registration paths:

• Free race: registration should be confirmed immediately
• Paid race: registration should stay pending until payment review is approved

That sounds simple, but it creates a design question: when a payment is approved, which service owns the registration state change?

Keep the State Transition with the Owning Context

My first instinct was the obvious one: if PaymentService.review() approves the payment, just update the registration there too.

That would work, but it would make the payment module responsible for registration lifecycle rules. I didn't want that coupling.

So I kept the payment review logic in PaymentService and emitted domain events:

this.eventEmitter.emit(NotificationEventTypes.PAYMENT_APPROVED, {
    paymentId: payment.id,
    registrationId: payment.registration.id,
});

and

this.eventEmitter.emit(NotificationEventTypes.PAYMENT_REJECTED, {
    paymentId: payment.id,
    registrationId: payment.registration.id,
    rejectionCount: rejectionCount,
});

Then RegistrationService listens:

@OnEvent(NotificationEventTypes.PAYMENT_APPROVED)
async handlePaymentApprovedEvent(event: {
    paymentId: string;
    registrationId: string;
}) {
    await this.prisma.registration.update({
        where: { id: event.registrationId },
        data: { status: 'CONFIRMED' },
    });
}

and:

@OnEvent(NotificationEventTypes.PAYMENT_REJECTED)
async handlePaymentRejectedEvent(event: {
    paymentId: string;
    registrationId: string;
    rejectionCount: number;
}) {
    if (
        event.rejectionCount >=
        this.configService.get<number>('MAX_PAYMENT_ATTEMPTS', 3)
    ) {
        await this.prisma.registration.update({
            where: { id: event.registrationId },
            data: { status: 'CANCELLED' },
        });
    }
}

That split turned out cleaner than I expected. Payment owns payment review. Registration owns registration status.

Free Races Should Skip the Pending State
I also adjusted registration creation to handle free races directly:

return await this.prisma.registration.create({
    data: {
        userId,
        raceId,
        ...(race.price === 0
            ? { status: RegistrationStatus.CONFIRMED }
            : {}),
    },
});

This removed the need for a separate confirmation step for zero-price races. The service can decide the initial state up front from the race price.

P2002 Is the Real Duplicate Guard

One of the more useful reminders today was about duplicate registrations.

At the application level, it's tempting to do:

1. check if the registration exists
2. if not, create it
3. That works in the happy path, but it's not enough under concurrency. Two requests can pass the pre-check before either insert commits.

The actual protection comes from the Prisma schema:

@@unique([userId, raceId])
and the create call needs to treat P2002 as the authoritative duplicate signal:

} catch (error) {
    if (
        error instanceof Prisma.PrismaClientKnownRequestError &&
        error.code === 'P2002'
    ) {
        throw new ConflictException('You are already registered for this race.');
    }

    throw error;
}

That changed how I think about the flow.

Pre-checks improve messaging and readability
Unique constraints enforce reality
They're not interchangeable.

Config Instead of Magic Numbers

The payment module originally had:

const MAX_PAYMENT_ATTEMPTS = 3;
I moved that behind ConfigService so the service reads from env instead:

this.configService.get<number>('MAX_PAYMENT_ATTEMPTS', 3)
Small change, but it matters. Retry limits are a policy decision, and policy is usually config, not hardcoded behavior.

Endpoint Work

I also finished the controller side so the flow is reachable in the app:

GET /events/:eventId/payments
PATCH /payments/:id/review
GET /registrations/:id
The review path uses existing org membership checks so admins can review event payments without opening up the endpoint to everyone.

Verification

Fresh verification for the session:

npm run build passed
targeted unit tests passed: 4 suites, 57 tests
e2e is partially blocked right now because the local test database on localhost:5433 was not running during the session
That last part matters. The code is in much better shape, but I don't want to blur “designed and unit-tested” with “fully e2e-verified.”

Takeaway

The useful lesson from today wasn't “how to add a payment review endpoint.” It was that a flow starts feeling solid when the owning modules each handle their own state transitions.

Payment review should not secretly become registration business logic.

Events were the clean line here.