Fidelidad de Plaza — compatibilidad con Mercado Pago

La respuesta Orders expone total_paid_amount y paid_amount de la transacción desde las unidades menores capturadas, separadas del importe solicitado y devuelto. El consumidor no debe inferir captura desde el total solicitado cuando falta esa evidencia. Verificado localmente contra el esquema Orders versionado. Revisión del 2026-09-06 usando los dos índices de llms/mercado-pago. El OpenAPI oficial y su checksum están en contracts/plaza/; la validación sigue siendo un subconjunto manual.

#Fuentes

Las referencias oficiales de creación, procesamiento, captura, devolución, estados y Checkout Pro.

#Superficie

Método	Ruta	Operación
POST	`/v1/orders`	crear
GET	`/v1/orders/{id}`	consultar
POST	`/v1/orders/{id}/transactions`	agregar una transacción
POST	`/v1/orders/{id}/process`	procesar
POST	`/v1/orders/{id}/capture`	capturar
POST	`/v1/orders/{id}/cancel`	cancelar
POST	`/v1/orders/{id}/refund`	devolver

Base: http://localhost:8080/plaza, con prefijo opcional y autenticación Bearer. Cada POST requiere X-Idempotency-Key de 1–128 caracteres; UUID v4 es una recomendación. processing_mode: manual crea una orden vacía; se agrega una transacción con POST /v1/orders/{id}/transactions (HTTP 201) antes de /process. Se rechazan procesar sin transacción y agregar una segunda. Los IDs usan ORD. capture_mode: manual autoriza y espera /capture. Son independientes. La captura es total, con cuerpo vacío. La devolución parcial utiliza transactions: [{ id: "<id del pago devuelto por la API>", amount: "10.00" }]; {} devuelve lo que queda capturado. El antiguo amount en la raíz se rechaza.

#Estados

Canónico	status	status_detail
created	created	created
requires_action	action_required	waiting_payment
authorized	action_required	waiting_capture
captured / settled	processed	accredited
devolución parcial	processed	partially_refunded
canceled	canceled	canceled
failed	failed	failed
refunded	refunded	refunded
disputed	charged_back	in_process

Los escenarios pueden sobrescribir el vocabulario. Los de pendiente y rechazo incluidos usan ahora los estados de Orders, sin mezclar los de Payments.

#Qué se emula

Creación, consulta, procesamiento, autorización, captura total, cancelación y reembolso total/parcial de una transacción sintética. IDs estables, importes por reembolso y fechas created_date/last_updated_date, sin devolver tokens de tarjeta. Idempotencia, locks, contabilidad, outbox y notificaciones firmadas compartidos. Mapeo de moneda para MLA, MLB, MLM, MLC, MCO, MPE y MLU.

El checkout conserva el nombre y tema de Plaza (terracota y arena), con el icono suministrado de Mercado Pago, medios de pago apilados, resumen del comercio e inicio opcional para saldo interno. Pix solo aparece para BRL y Pago Fácil para ARS. Los controles de simulación son secundarios.

El checkout respeta la captura manual: autoriza sin cobrar; la API captura después.

#Qué no se emula

Desde la migración 20261026000100, cada reembolso se persiste junto con su asiento y el GET de la orden lo devuelve en transactions.refunds[], con el mismo ID e importe que el POST. Se prueban devoluciones parciales concurrentes del mismo importe, replay, reconstrucción del servidor y aislamiento por cuenta. Los totales históricos anteriores no se convierten en movimientos inventados. No se emulan reembolsos asíncronos pendientes/fallidos. La guía oficial de migración de Checkout API documenta esta consulta (revisión 2026-10-27). Se conserva intacto el snapshot OpenAPI anterior; su ausencia de esquema de historial queda como límite explícito.

OpenAPI completo: validación parcial de campos, métodos, totales y errores.
El SDK oficial mercadopago@3.6.0 no permite cambiar el host mediante su configuración pública. Se verifica su validador de firmas, no sus peticiones.
Tokenización, QR/Pix, cupones, cuotas ni procesamiento asíncrono real. Un escenario y la confirmación local determinan el resultado.
Preferences y Checkout Pro. La URL local es una capacidad del plano de control, no un init_point; el kit es la identidad independiente de Plaza, no el SDK ni una réplica.
Múltiples transacciones, modificación/eliminación de la transacción agregada, pagos divididos y marketplace. Se permite agregar una a una orden manual vacía.
Fidelidad completa de devoluciones: conversión según el sitio configurado, sin usar currency_id sintético para devoluciones entre monedas; sin colección de historial independiente. Las devoluciones ya responden HTTP 201.
Errores completos de Orders: varios errores internos conservan el formato antiguo error/message/status/cause.
Tarifas reales. 2,9 % + 0,30, reserva de siete días y disputa sin comisión son parámetros sintéticos configurables, no precios regionales verificados.

#Contracargos individuales (0.1.1-alpha.1)

El subconjunto GET /v1/chargebacks/{id} sigue la referencia oficial y la gestión de contracargos de Orders. El snapshot importado de Orders no incluye un esquema legible por máquina para este recurso. Es un subconjunto documentado, no una certificación del proveedor.

Configurar bankingProfile.providerMerchantId numérico antes de abrir el caso. La acción de contracargo del operador devuelve disputeId; la ruta de control POST /applications/:applicationId/payments/:intentId/chargeback/resolve acepta { "outcome": "won" } o lost. La lectura requiere el bearer de la aplicación y X-Caller-Id coincidente; atraviesa el pipeline de escenarios y trazas. El caso conserva vendedor, moneda, principal, comisión y partes contables. Abrir debita una vez; ganar revierte ese débito una vez; perder lo conserva. coverage_applied vale null/true/false respectivamente. No se admite cambiar una resolución terminal.

Límites: un caso y una transacción sintética por orden; sin documentos, plazos, casos agrupados ni webhook automático de contracargo. Los casos conocidos se recuperan consultándolos. No se inventan casos para débitos históricos sin ID. Se conservan los IDs sintéticos PAY...; importes fuera de representación numérica exacta se rechazan. Una aplicación sin vendedor declarado conserva la acción antigua, pero no expone un caso consultable. No acredita un merchant real.