Skip to content
Payment Emulator LabDocumentation
Open console
On this page

Fidelity and limits

Mercado Pago emulator fidelity

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 nowlive in contracts/mercadopago/.

3 min read

Í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/mercadopago/. Validation remains an explicitly limited subset.

#Sources

#Surface

Method Path Operation
POST /v1/orders payment.create
GET /v1/orders/{id} payment.get
POST /v1/orders/{id}/transactions payment.update
POST /v1/orders/{id}/process payment.confirm
POST /v1/orders/{id}/capture payment.capture
POST /v1/orders/{id}/cancel payment.cancel
POST /v1/orders/{id}/refund payment.refund

Base URL: http://localhost:8080/mercadopago, 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

Canonical status status_detail
created created created
requires_action action_required waiting_payment
authorized action_required waiting_capture
captured / settled processed accredited
partially refunded processed partially_refunded
canceled canceled canceled
failed failed failed
refunded refunded refunded
disputed charged_back in_process

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

  • 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. It has a Mercado Pago blue/white identity, stacked method selection, merchant summary and optional internal-balance sign-in. Simulation controls are secondary.

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

#What is not emulated

  • 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 an approximation, not a captured replica or the 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.
Payment Emulator Lab · RonuSoftwareMIT