Payments validate endpoint

TLDR: adds POST /api/v2/payments/validate to check if a customer (by email) has overdue payments before checkout.

Status: completed Created: 2026-09-08 Owner: @brunoandradd

Context

Checkout needs a way to pre-validate, by email, whether a customer has overdue payments before allowing a new purchase. This mirrors the existing rule in Api::V1::CheckoutController#validate_customer_can_purchase_having_overdue_payments, exposed as a standalone endpoint.

Objectives

  • Expose POST /api/v2/payments/validate receiving { email, product_id }
  • Return { valid: true, message: "" } when the customer has no overdue payment (or doesn’t exist)
  • Return { valid: false, message: "Não foi possível continuar com sua compra neste momento. Entre em contato com o suporte para verificar sua situação e receber as orientações necessárias." } when the customer has at least 1 overdue payment
  • product_id is accepted but ignored for now (no validation tied to it)

Changes

  • config/routes.rb: inside namespace :v2, add post "payments/validate", to: "payments/validates#create"
  • app/controllers/api/v2/payments/validates_controller.rb (new): Api::V2::Payments::ValidatesController#create
    • looks up Customer.find_by(email: params[:email])
    • if customer is blank or !customer.is_in_debt? → render json: { valid: true, message: "" }
    • if customer.is_in_debt? → render json: { valid: false, message: "Não foi possível continuar com sua compra neste momento. Entre em contato com o suporte para verificar sua situação e receber as orientações necessárias." }
    • always responds with HTTP 200
    • reuses existing Customer#is_in_debt? (app/models/customer.rb:47), no new business logic in the model
  • spec/requests/api/v2/payments/validates_spec.rb (new): request spec covering
    • without auth → forbidden
    • customer not found by email → valid: true
    • customer found, no overdue payment → valid: true
    • customer found, with overdue payment → valid: false + error message

How to verify

  • bundle exec rspec spec/requests/api/v2/payments/validates_spec.rb
  • Manual: POST /api/v2/payments/validate with access-token header and { "email": "...", "product_id": "..." }, checking both a customer with and without an overdue payment

Documentation

No documentation changes needed.