Plaza fidelity — Mercado Pago compatibility

Índice / Index · Español

Reviewed on 2026-09-06 using llms/mercado-pago/llms.md and llms-api.md. These are documentation indexes. The official Orders snapshot and SHA-256 now live in contracts/plaza/. Validation remains an explicitly limited subset.

#Sources

• Create order.
• Process order.
• Full capture.
• Refund order.
• Order statuses.
• Checkout Pro visual reference.

#Surface

Base URL: http://localhost:8080/plaza, with optional provider prefix. Credentials use Bearer authentication. Every listed POST requires X-Idempotency-Key: 1–128 characters, with UUID v4 recommended, not mandatory.

processing_mode: manual creates an empty order without attempting payment. Add one payment with POST /v1/orders/{id}/transactions (HTTP 201), then /process attempts it. Processing without a transaction and adding a second transaction are refused. Synthetic order identifiers now use the ORD prefix. capture_mode: manual authorizes and waits for /capture. These independent settings are no longer conflated. The capture endpoint accepts an empty body and captures the full amount. A partial refund uses transactions: [{ id: "<returned payment id>", amount: "10.00" }]; {} refunds the remaining captured amount. The old top-level amount alias is refused.

#State vocabulary

A scenario can override this vocabulary; its author is responsible for any intentional deviation. The supplied pending and rejected scenarios use Orders vocabulary rather than legacy Payments status details.

#What is emulated

Individual refunds created after migration 20261026000100 are persisted with the ledger transaction and returned by order GET in transactions.refunds[]. The POST response and later GET use the same refund ID and exact amount, including concurrent partial refunds of equal amounts. Repeating a command uses the original idempotency response. Earlier aggregate totals are not backfilled into invented individual movements. Processing/failed asynchronous refunds remain unsupported. This GET shape is documented in the official Checkout API migration guide, reviewed 2026-10-27. The older imported OpenAPI snapshot is preserved unchanged; its missing refund-history schema is an explicit coverage gap.

• Creation, retrieval, processing, authorization, full capture, cancellation and full/partial refunds for one synthetic transaction per order.
• Stable payment IDs, per-refund amounts and response timestamps created_date and last_updated_date. Card tokens are not echoed in transaction responses.
• Shared idempotency, locking, ledger and outbox behavior; signed order notifications.
• Site-to-currency mapping for MLA, MLB, MLM, MLC, MCO, MPE and MLU.
• The checkout offers Pix only for BRL and Pago Fácil only for ARS. Plaza keeps its name and terracotta/sand theme, with the supplied Mercado Pago icon, stacked method selection, merchant summary and optional internal-balance sign-in.

Buyer completion respects manual capture: it authorizes first, without collecting funds. A later API capture collects the money.

#What is not emulated

The Orders response exposes total_paid_amount and transaction paid_amount from captured minor units, independently of the requested and refunded totals. Consumers must not infer a captured amount from the requested total when that evidence is absent. Verified locally against the checked-in Orders schema.

• Full OpenAPI validation is not implemented. Required fields, payment types, totals and error details are not validated against the complete schema.
• The official SDK cannot be pointed at the emulator through its public configuration. The installed mercadopago@3.6.0 hardcodes its API host. Its stateless webhook signature validator is tested; request compatibility is not SDK-verified.
• Method-specific execution is not modeled. No tokenization, QR/Pix flow, cash voucher, installments or real asynchronous processing; a scenario and local checkout completion decide the result. Method names alone are not proof of compatibility with those products.
• Preferences and Checkout Pro are not implemented. The buyer URL is a local control-plane capability for an Orders resource, not an official init_point. The visual kit is Plaza's independent identity, not a replica or provider SDK.
• Multiple payment transactions are refused. Adding one transaction to an empty manual order is supported; updating or deleting it, split payments and marketplace behavior are not implemented.
• Refund fidelity is incomplete. Currency conversion uses the configured site; a synthetic currency_id override must not be used for cross-currency refunds. Refund history is not a separate resource collection and successful refunds now return the documented HTTP 201.
• Errors remain a legacy subset. Several core refusals use the older error/message/status/cause mapping rather than current Orders error codes.
• Accounting is synthetic. 2.9% + 0.30, seven-day reserve release and zero dispute fee are configurable simulation parameters, not verified regional Mercado Pago pricing. Real schedules and financing costs vary.

#Individual chargebacks (0.1.1-alpha.1)

The selected GET /v1/chargebacks/{id} shape follows the official chargeback reference and Orders chargeback management. No machine-readable chargeback schema is present in the imported Orders snapshot; this is a documented subset, not full provider certification.

Set an explicit numeric bankingProfile.providerMerchantId on the test application before opening a case. The operator's chargeback action returns disputeId; POST /applications/:applicationId/payments/:intentId/chargeback/resolve takes { "outcome": "won" } or lost. Provider reads require the application bearer and matching X-Caller-Id. They pass through the normal scenario/trace pipeline. The case snapshots its seller, currency, principal, fee and ledger parties. An opened case debits once; a win reverses that debit once; a loss keeps it. coverage_applied is null/true/false respectively. Terminal conflicts are rejected.

Limits: one case and one synthetic payment transaction per order; no submission of documents, deadlines, grouped cases or automatic chargeback webhook. Known cases are recovered by read-only polling. Existing historical debits without case IDs are not fabricated into cases. Synthetic PAY... transaction IDs remain unchanged. Numeric response amounts outside exact representability are rejected. Sandboxes without a provider merchant retain the old control action but cannot expose a provider-readable case. This does not establish a real merchant identity.