PaymentEvent.java

package com.checkout.paymentgw.events;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;

import java.time.Instant;
import java.util.UUID;

/**
 * Single envelope for all payment-related events on the {@code payments.events} topic.
 * <p>
 * Wire-level contract — keep <strong>backward-compatible</strong>:
 * <ul>
 *   <li>Add new fields only (defaulted, nullable).</li>
 *   <li>Never rename or remove a field without a major version bump.</li>
 *   <li>Consumers must ignore unknown fields.</li>
 * </ul>
 *
 * @param eventId unique id for at-least-once de-duplication on consumers
 * @param eventType {@link EventType#name()}
 */
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonIgnoreProperties(ignoreUnknown = true)
public record PaymentEvent(
        String eventId,
        String eventType,
        UUID paymentId,
        String merchantId,
        String currency,
        Integer amount,
        String cardNumberLastFour,
        String status,
        String reason,
        Instant occurredAt,
        String correlationId
) {

    public enum EventType {
        PAYMENT_SUBMITTED,
        PAYMENT_AUTHORISED,
        PAYMENT_DECLINED,
        PAYMENT_FAILED,
        PAYMENT_REVERSED
    }

    public static Builder builder() {
        return new Builder();
    }

    public static final class Builder {
        private String eventId;
        private String eventType;
        private UUID paymentId;
        private String merchantId;
        private String currency;
        private Integer amount;
        private String cardNumberLastFour;
        private String status;
        private String reason;
        private Instant occurredAt;
        private String correlationId;

        public Builder eventId(String v)            { this.eventId = v; return this; }
        public Builder eventType(EventType v)       { this.eventType = v.name(); return this; }
        public Builder paymentId(UUID v)            { this.paymentId = v; return this; }
        public Builder merchantId(String v)         { this.merchantId = v; return this; }
        public Builder currency(String v)           { this.currency = v; return this; }
        public Builder amount(Integer v)            { this.amount = v; return this; }
        public Builder cardNumberLastFour(String v) { this.cardNumberLastFour = v; return this; }
        public Builder status(String v)             { this.status = v; return this; }
        public Builder reason(String v)             { this.reason = v; return this; }
        public Builder occurredAt(Instant v)        { this.occurredAt = v; return this; }
        public Builder correlationId(String v)      { this.correlationId = v; return this; }

        public PaymentEvent build() {
            return new PaymentEvent(eventId, eventType, paymentId, merchantId, currency, amount,
                    cardNumberLastFour, status, reason, occurredAt, correlationId);
        }
    }
}