fix(orders): tighten shipping address, line, and item schema constraints

[leofischer]

Summary

Aligns the OpenAPI schemas for order shipping address, shipping line, line item, checkout, card/BNPL payment methods, and metadata with the validations actually enforced by payments-api's sanitizers at v2.3.0. Every constraint was verified against payments-api source, then adversarially re-reviewed by four independent passes that re-derived each bound from code; their confirmed findings are incorporated.

Targets release/v2.3.0.

Changes

Shipping (original scope)

• Shared schemas/customers/shipping_contact_address.yml; create requires street1/postal_code/country (update does not); MX 5-digit postal-code rule; min/max lengths per the strict StringValidator bounds (max = less_than − 1 = 249; min = greater_than + 1). postal_code keeps 250 (its only cap is the inclusive model-level zip rule). City documents the enforced two-consecutive-letters pattern.

Checkout / order (validated with team rulings)

• exclude_card_networks enum → [visa_master_card, amex] (exact-membership validator; visa/mastercard are rejected). Responses return snake_case — an earlier CamelCase-echo claim was refuted in adversarial review (Checkout.to_snake_case underscores values on every read) and removed.
• three_ds_mode → adds accepted value not_strict; null defers to company-level 3DS configuration (it does not disable 3DS); not_strict is behaviorally identical to strict in payments-api (attempt acceptance is company-config, not mode). Create-only wording kept for checkouts (update cleaner permits nothing) and dropped for orders (permitted+persisted on update, validated on create).
• Order/line-item/tax/shipping metadata: values documented as scalar string(≤249)/integer/number/boolean via anyOf (adversarial review caught that oneOf rejects integers, which match both integer and number). Worded as "not supported" rather than "rejected": per team direction payments-api keeps its current partial per-key enforcement, so the docs state the contract without over-promising server-side rejection.
• maxProperties: 100 retained/extended as the documented contract. Known gap: payments-api does not enforce it (characterization specs pinning this landed in conekta/payments-api#6466); closing it is a future product decision.

Payment methods

• BNPL: cancel_url is optional by design (spec-pinned in payments-api); can_not_expire removed (silently stripped by the cleaner); expires_at added (unix seconds; defaults to one month). Note: its datatype is currently unvalidated server-side (non-Integer 500s) — documented contract is integer.
• Card: two-word cardholder name rule (letters only) + maxLength: 249; contract_id exposed (exactly 10 chars, create-only, stored as bank_contract_id, echoed in charge responses since v2.1.0; carries a do-not-put-sensitive-data caveat).
• Fiscal entity address: residential removed — stripped by the cleaner and not storable on FiscalEntityAddress (the field exists only on ShippingAddress).

Verification

• make merge rebuilds cleanly; bundler deduplicates the metadata value schema into a single shared component.
• Adversarial review: 4 independent passes over the full diff, every constraint re-derived from payments-api source with file:line proof. Findings fixed: oneOf→anyOf, CamelCase echo claim removed, order three_ds_mode create-only wording dropped, null semantics corrected, not_strict description made honest, city pattern documented.

Related

• conekta/payments-api#6466 — characterization specs pinning the documented-but-unenforced gaps (metadata cap, per-key nested checks, BNPL types). Specs only; no behavior change.

🤖 Generated with Claude Code

[atlantis-conekta]

Error: This repo is not allowlisted for Atlantis.

[leofischer]

Second adversarial review — consolidated verdict

Five independent reviewers (two removal deep-dives + three full-quadrant passes) re-derived every changed line of this PR from payments-api validators, views, and specs. One reviewer empirically executed the TypeValidator to settle null handling.

Both questioned removals confirmed correct:

• can_not_expire (BNPL): never existed in the BNPL sanitizer — git log -S returns empty since the sanitizer's creation; all 26 codebase references belong to checkout/cash/OXXO/SPEI flows where the field remains documented. The two stale BNPL request examples still sending it are now cleaned.
• residential (fiscal address): no Mongoid field on FiscalEntityAddress/Address, not in attr_accessible, stripped or blocked on every route (including nested fiscal_entities on customer create, where the cleaner passes the subtree but mass-assignment strips it), never rendered by any view, never touched by a spec. The residential: true values in order examples sit under shipping_contact.address, where the field is real and stays documented.

Errors found in the previous revision, now fixed:

• order three_ds_mode: explicit null is rejected on create (type: String check — empirically reproduced), so the nullable type/enum was wrong; and nil means no 3DS via the API, not company-config deferral (that fallback only applies via Checkout or antifraud). Checkout keeps nullable (it is also the response schema) with omit-vs-null semantics explained.
• not_strict summaries now say 3DS2 flow (challenge vs frictionless is issuer-side).
• card name description no longer implies , . ' - and accented letters are rejected (the regex allows them).
• tax description.minLength corrected 2 → 3 (strict greater_than: 2).
• between_streets now documents its enforced maxLength 249 + two-consecutive-letters pattern.
• klarna_bnpl deliberately NOT added to product_type despite being parser-accepted — not publicly available.

Pre-existing spec-modeling issues flagged for follow-up (not touched):

• charge_request.yml payment_method oneOf includes a catch-all payment_method_general_request branch — a valid BNPL request matches two branches, which strict oneOf validators reject. Should be anyOf or discriminated.
• checkout_request.yml never documented can_not_expire even though checkout sanitizers accept it (docs gap in the opposite direction).
• payments-api accepts order three_ds_mode on update unvalidated (arbitrary strings persist and silently degrade) — documented in conekta/payments-api#6466's gap table.

🤖 Generated with Claude Code