Payment API Design

{
  "processId": "uuid",
  "processState": "DONE",
  "order": {
    "id": 123,
    "number": "WC-45678",
    "status": "PENDING",
    "transactionDateTime": "2025-01-01T10:00:00Z",
    ...
  },
  "paymentUrl": "https://woocommerce.example.com/checkout/order-pay/45678/?key=..."
}

{
  "processId": "uuid",
  "processState": "DONE",
  "order": { /* full OrderDTO */ },
  "paymentUrl": "https://..."
}

{
  "processId": "uuid",
  "processState": "DONE",
  "orderId": 123
}

{
  "id": 123,
  "number": null,
  "referenceCode": null,
  "status": "UNPAID",
  "transactionDateTime": "2025-01-01T10:00:00Z",
  "buyer": {
    "name": "John Smith"
  },
  "organisation": {
    "id": 1,
    "name": "Cycling Club SA"
  },
  "lineItems": [
    {
      "id": 1,
      "description": "Adult Membership 2025",
      "personName": "John Smith",
      "quantity": 1,
      "unitPrice": 500.00,
      "totalPrice": 500.00
    },
    {
      "id": 2,
      "description": "Junior Membership 2025",
      "personName": "Jane Smith",
      "quantity": 1,
      "unitPrice": 250.00,
      "totalPrice": 250.00
    }
  ],
  "totalAmount": 750.00,
  "availablePaymentMethods": ["ONLINE", "EFT", "MANUAL"]
}

{
  "paymentMethod": "ONLINE"
}

{
  "paymentMethod": "ONLINE",
  "paymentUrl": "https://woocommerce.example.com/checkout/order-pay/45678/?key=...",
  "externalOrderId": "WC-45678"
}

{
  "paymentMethod": "EFT",
  "referenceCode": "B-324",
  "bankingDetails": {
    "bankName": "Standard Bank",
    "accountName": "Cycling Club SA",
    "accountNumber": "1234567890",
    "branchCode": "051001",
    "reference": "B-324"
  }
}

{
  "paymentMethod": "MANUAL",
  "referenceCode": "B-324"
}

public class ReferenceCodeGenerator {

    // Alphabet excluding O and I (24 letters)
    private static final String DAY_PREFIXES = "ABCDEFGHJKLMNPQRSTUVWXYZ";

    /**
     * Generate a reference code for the given date and sequence.
     * @param date The date for the day prefix
     * @param dailySequence The sequence number for the day (1-based)
     * @return Reference code like "B-324" or "C-A5F"
     */
    public String generate(LocalDate date, int dailySequence) {
        int dayOfYear = date.getDayOfYear();
        char prefix = DAY_PREFIXES.charAt((dayOfYear - 1) % 24);

        String sequence;
        if (dailySequence <= 999) {
            sequence = String.format("%03d", dailySequence);
        } else {
            // Switch to hex for sequences > 999
            sequence = String.format("%03X", dailySequence - 1000 + 0xA00);
        }

        return prefix + "-" + sequence;
    }
}

@Entity
@Table(name = "sales_order")
public class Order {
    // ... existing fields ...

    @Size(max = 8)
    @Column(name = "reference_code", length = 8)
    private String referenceCode;
}

@Embeddable
public class BankingDetails {
    @Column(name = "eft_availability", length = 1)
    @Convert(converter = EftAvailabilityVarChar1Converter.class)
    private EftAvailability availability;

    @Size(max = 100)
    private String bankName;

    @Size(max = 100)
    private String accountName;

    @Size(max = 50)
    private String accountNumber;

    @Size(max = 20)
    private String branchCode;
}

// In RegistrationSystem entity
@Column(name = "payment_methods", length = 50)
@Convert(converter = PaymentMethodListConverter.class)
private List<PaymentMethod> availablePaymentMethods;

public enum PaymentMethod {
    ONLINE("O"),   // Credit card via WooCommerce
    EFT("E"),      // Electronic funds transfer
    MANUAL("M");   // Pay at counter/clubhouse

    private final String code;

    PaymentMethod(String code) {
        this.code = code;
    }

    public String getCode() {
        return code;
    }

    public static PaymentMethod fromCode(String code) {
        for (PaymentMethod method : values()) {
            if (method.code.equals(code)) {
                return method;
            }
        }
        throw new IllegalArgumentException("Unknown PaymentMethod code: " + code);
    }
}

public class PaymentRequestDTO {
    @NotNull
    private PaymentMethod paymentMethod;

    // Getters and setters
}

public class PaymentResponseDTO {
    private PaymentMethod paymentMethod;

    // ONLINE only
    private String paymentUrl;
    private String externalOrderId;

    // EFT, MANUAL only
    private String referenceCode;

    // EFT only
    private BankingDetailsDTO bankingDetails;

    // Getters and setters
}

public class BankingDetailsDTO {
    private String bankName;
    private String accountName;
    private String accountNumber;
    private String branchCode;
    private String reference;  // The reference code to use

    // Getters and setters
}

public class OrderDTO {
    // ... existing fields ...

    // New fields
    private String referenceCode;
    private List<OrderLineItemDTO> lineItems;
    private BigDecimal totalAmount;
    private List<PaymentMethod> availablePaymentMethods;
}

public class OrderLineItemDTO {
    // ... existing fields ...

    // New/enhanced fields
    private String description;   // Product name or membership type
    private String personName;    // Person this line item is for
    private BigDecimal unitPrice;
    private BigDecimal totalPrice;
}

-- Add reference_code to sales_order
ALTER TABLE sales_order
ADD COLUMN reference_code VARCHAR(8);

-- Add banking details to registration_system
ALTER TABLE registration_system
ADD COLUMN eft_availability VARCHAR(1) DEFAULT 'D',
ADD COLUMN bank_name VARCHAR(100),
ADD COLUMN account_name VARCHAR(100),
ADD COLUMN account_number VARCHAR(50),
ADD COLUMN branch_code VARCHAR(20);

-- Add available payment methods to registration_system
ALTER TABLE registration_system
ADD COLUMN payment_methods VARCHAR(50) DEFAULT 'ONLINE';