feat(msi): add POST /monthly_installments/validate to the spec

[leofischer]

What

Adds POST /monthly_installments/validate to the spec. The endpoint exists and the public dev center documents it, but it is absent here, so no SDK exposes it.

• payments-api config/routes.rb:736 → MonthlyInstallmentsController#validate
• Documented publicly at dev-center docs/PAGOS A LA MEDIDA CON DIRECT API/aceptar-pagos-con-tarjetas-1/meses-sin-intereses-api.md as step 1 of the Direct API MSI flow, with a curl example and a full field table

Merchants are currently told to call an endpoint their SDK has no method for.

Schema derivation

Everything comes from BinValidatorService, not from the docs:

Field	Source
bin — 6 or 8 digits, 8 retried as 6 on no match	BIN_SIZE = 8; #load_bin_information_with_fallback (@bin = bin[0..5])
amount — minor units	#calculate_monthly_installments (amount / months.to_f)
available_installments[].months / .amount	#calculate_monthly_installments, #adapt_engine_options (monthly_fee → amount)
bin_info — country, scheme, issuer	#bin_info_summary (exactly these three keys)
both top-level keys always present	#retrieve_legacy and #retrieve_via_engine both return the same two keys
months ∈ {3, 6, 9, 12, 18, 24}	MONTHLY_INSTALLMENTS = [3, 6, 9, 12, 18, 24]

available_installments is documented as legitimately empty rather than an error case: #retrieve_monthly_installments returns [] when validate_card_rules? fails (debit, or credit not issued in Mexico). Client code that treats "no error" as "MSI available" will offer plazos the charge then rejects. Same note is going into the dev center in conekta/dev-center#55.

Verification

resources/, requestBodies/ and schemas/ follow the tokens/ layout exactly. Every $ref reachable from api.yaml resolves and every file parses — 276 files walked.

_build/api.yaml is not regenerated: make merge needs a running Docker daemon and none was available here. Run make merge before merging.

Why this is a draft — please confirm the endpoint is public surface

MonthlyInstallmentsController carries the comment "Add MSI validation for checkout-fe". It was built for Conekta's own checkout frontend, and adding it here generates public SDK methods in every language, which is a commitment to its stability. Two ways to resolve, and it is your call which:

1. It is public surface (the dev center already treats it as such) → merge this.
2. It is internal → close this, and the MSI page in the dev center should stop telling merchants to call it.

Either way the current state is inconsistent.

Two other spec gaps I found and did NOT add

Both exist in payments-api and appear in public dev center pages, but I have no evidence they are intended as public API surface, and I will not invent a contract for them:

• POST /payees — config/routes.rb:495, under ApiConstraints version scoping, so which API versions expose it also needs confirming. Appears in generar-una-dispersión-a-terceros-con-direct-api.md:79.
• PUT / GET /checkout_configuration — config/routes.rb:383. Appears in hosted-payments.md:905.

Worth a decision alongside this one.