{ "openapi": "3.1.0", "info": { "title": "MercadoPago API", "description": "The MercadoPago REST API. Please see https://www.mercadopago.com/developers for more details.", "termsOfService": "https://www.mercadopago.com/developers/es/docs/resources/legal/terms-and-conditions", "contact": { "name": "MercadoPago Developer Experience", "url": "https://www.mercadopago.com/developers" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.mercadopago.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "OAuth", "description": "Authorization flows for marketplace on-behalf-of and Wallet Connect", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Preferences", "description": "Checkout Pro — redirect-based hosted checkout via Preferences", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Payments", "description": "Create and manage payment transactions", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Orders", "description": "Checkout API via Orders — recommended for new custom checkout integrations", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Merchant Orders", "description": "Order containers that group payments for a single purchase", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Customers", "description": "Customer profiles and stored payment methods", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Cards", "description": "Saved cards and card tokenization", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Addresses", "description": "Customer shipping and billing addresses", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Payment Methods", "description": "Available payment methods and installment plans per country", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Identification Types", "description": "Country-specific identity document type catalog", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Cancellations & Refunds", "description": "Cancel payments and create full or partial refunds", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Chargebacks", "description": "Chargeback dispute management", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Subscriptions", "description": "Recurring payment subscriptions", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Plans", "description": "Subscription billing plans", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Invoices", "description": "Subscription billing invoices", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Wallet Connect", "description": "OAuth-based wallet agreement flows for Wallet Connect", "x-mp-sites": [ "MLA", "MLB", "MLM" ] }, { "name": "Stores", "description": "Physical store locations", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "POS", "description": "Point of sale device management", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Terminals", "description": "Point hardware terminal management and print actions", "x-mp-sites": [ "MLA", "MLB", "MLC", "MLM" ] }, { "name": "Point Deprecated", "description": "Deprecated Point integration APIs — use Terminals and Point Orders instead", "x-mp-sites": [ "MLA", "MLB", "MLM" ] }, { "name": "QR Orders", "description": "In-store payment orders associated with QR codes", "x-mp-sites": [ "MLA", "MLB", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "QR Integrator", "description": "Integrator configuration for QR in-store", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "QR Deprecated", "description": "Deprecated in-store QR order endpoints (V1, V2, Dynamic QR)", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Claims", "description": "Post-sale claim details and search", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Claim Messages", "description": "Messages and file attachments within a claim", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Claim Resolutions", "description": "Mediation requests and expected resolutions", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Claim Shipping", "description": "Upload shipping evidence to support a claim", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Releases Report", "description": "Generate and schedule releases (settlement) reports", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Settlements Report", "description": "Generate and schedule all-transactions reports", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, { "name": "Payouts", "description": "Bank transfer and Pix payouts", "x-mp-sites": [ "MLA", "MLB", "MLM", "MLC" ] } ], "paths": { "/v1/payments": { "post": { "operationId": "createPayment", "summary": "Create a payment", "description": "Creates a payment. For card payments, generate a card token client-side via MercadoPago.js before calling this endpoint. For cash/offline methods (Boleto, OXXO, Pix), the response includes a payment URL in `transaction_details.external_resource_url`.\n**Idempotency**: Include `X-Idempotency-Key` to safely retry on network errors without risk of double charges.\n**Recommendation**: For new integrations, prefer the Orders API (`POST /v1/orders`).\n**Idempotent:** Supports `X-Idempotency-Key` header to safely retry without duplicate charges.\n**Webhook events triggered:** payment, merchant_order", "tags": [ "Payments" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Unique key per payment attempt. If you retry with the same key and the original payment was processed, MP returns the original result without creating a duplicate." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" }, "examples": { "card_brazil": { "summary": "Credit card — Brazil (Visa)", "value": { "transaction_amount": 100.5, "token": "YOUR_ACCESS_TOKEN", "description": "Premium subscription — 1 month", "installments": 1, "payment_method_id": "visa", "payer": { "email": "test@example.com", "identification": { "type": "CPF", "number": "12345678909" } } } }, "pix_brazil": { "summary": "Pix — Brazil", "value": { "transaction_amount": 100.5, "payment_method_id": "pix", "payer": { "email": "test@example.com", "identification": { "type": "CPF", "number": "12345678909" } } } }, "boleto_brazil": { "summary": "Boleto Bancário — Brazil", "value": { "transaction_amount": 100.5, "payment_method_id": "bolbradesco", "payer": { "email": "test@example.com", "first_name": "João", "last_name": "Silva", "identification": { "type": "CPF", "number": "12345678909" } } } }, "card_argentina": { "summary": "Credit card — Argentina (Visa)", "value": { "transaction_amount": 5000.0, "token": "YOUR_ACCESS_TOKEN", "description": "Order #1234", "installments": 3, "payment_method_id": "visa", "payer": { "email": "test@example.com", "identification": { "type": "DNI", "number": "12345678" } } } }, "oxxo_mexico": { "summary": "OXXO — Mexico", "value": { "transaction_amount": 500.0, "payment_method_id": "oxxo", "date_of_expiration": "2024-12-31T23:59:59.000-06:00", "payer": { "email": "test@example.com" } } } } } } }, "responses": { "201": { "description": "Payment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "200": { "description": "Payment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } } } } }, "/v1/payments/{id}": { "get": { "operationId": "getPayment", "summary": "Get payment by ID", "tags": [ "Payments" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Payment ID" } ], "responses": { "200": { "description": "Payment found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "put": { "operationId": "updatePayment", "summary": "Update or capture a payment", "description": "Update payment fields or capture an authorized payment. To capture an authorized two-step payment: send `{\"capture\": true}`. To cancel an authorized payment: send `{\"status\": \"cancelled\"}`.", "tags": [ "Payments" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentUpdateRequest" } } } }, "responses": { "200": { "description": "Payment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/payments/search": { "get": { "operationId": "searchPayments", "summary": "Search payments", "tags": [ "Payments" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sort", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "criteria", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "external_reference", "in": "query", "schema": { "type": "string" } }, { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "date_created", "date_last_updated", "money_release_date" ] } }, { "name": "begin_date", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "in": "query", "schema": { "type": "string" } }, { "name": "pos_id", "in": "query", "schema": { "type": "string" } }, { "name": "collector.id", "in": "query", "schema": { "type": "string" } }, { "name": "payer.id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSearchResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/payments/{id}/refunds": { "post": { "operationId": "createRefund", "summary": "Create a refund", "description": "Creates a full or partial refund for an approved payment. Omit the `amount` field for a full refund. Partial refunds are supported; multiple partials are allowed up to the original transaction amount.\n**Idempotent:** Supports `X-Idempotency-Key` header to safely retry without duplicate charges.", "tags": [ "Cancellations & Refunds" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Payment ID to refund" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" }, "examples": { "full_refund": { "summary": "Full refund (omit amount)", "value": {} }, "partial_refund": { "summary": "Partial refund of R$50", "value": { "amount": 50.0 } } } } } }, "responses": { "201": { "description": "Refund created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "payment_id": { "type": "integer" }, "amount": { "type": "number", "format": "float" }, "metadata": { "type": "object", "additionalProperties": true }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "date_created": { "type": "string", "format": "date-time" }, "unique_sequence_number": { "type": "string" }, "refund_mode": { "type": "string", "enum": [ "standard", "instant" ] }, "adjustment_amount": { "type": "number", "format": "float", "nullable": true }, "status": { "type": "string", "enum": [ "approved", "in_process", "rejected" ] }, "reason": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "partition_details": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "operationId": "listRefunds", "summary": "List refunds for a payment", "tags": [ "Cancellations & Refunds" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Refund list", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "payment_id": { "type": "integer" }, "amount": { "type": "number", "format": "float" }, "metadata": { "type": "object", "additionalProperties": true }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "date_created": { "type": "string", "format": "date-time" }, "unique_sequence_number": { "type": "string" }, "refund_mode": { "type": "string", "enum": [ "standard", "instant" ] }, "adjustment_amount": { "type": "number", "format": "float", "nullable": true }, "status": { "type": "string", "enum": [ "approved", "in_process", "rejected" ] }, "reason": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "partition_details": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/payments/{id}/refunds/{refund_id}": { "get": { "operationId": "getRefund", "summary": "Get a specific refund", "tags": [ "Cancellations & Refunds" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "refund_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Refund found", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "payment_id": { "type": "integer" }, "amount": { "type": "number", "format": "float" }, "metadata": { "type": "object", "additionalProperties": true }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "date_created": { "type": "string", "format": "date-time" }, "unique_sequence_number": { "type": "string" }, "refund_mode": { "type": "string", "enum": [ "standard", "instant" ] }, "adjustment_amount": { "type": "number", "format": "float", "nullable": true }, "status": { "type": "string", "enum": [ "approved", "in_process", "rejected" ] }, "reason": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "partition_details": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/orders": { "post": { "operationId": "createOrder", "summary": "Create an order", "description": "Creates an Order for processing payment transactions. Supports automatic (single-stage, set processing_mode=automatic) and manual (multi-stage, set processing_mode=manual) modes.\n\nIn automatic mode, include the transactions.payments array with the payment method. In manual mode, omit transactions and add them later via POST /v1/orders/{id}/transactions, then trigger processing with POST /v1/orders/{id}/process.\n\nAvailable for: credit card, debit card, Pix (MLB), Boleto (MLB), OXXO (MLM), SPEI (MLM), PSE (MCO), Rapipago (MLA), Pago Fácil (MLA).", "tags": [ "Orders" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique key per order creation attempt. Prevents duplicate orders on retry." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" }, "examples": { "credit_card": { "summary": "Credit card — all countries", "value": { "type": "online", "processing_mode": "automatic", "total_amount": "100.00", "external_reference": "ORDER-2024-001234", "payer": { "email": "customer@example.com" }, "transactions": { "payments": [ { "amount": "100.00", "payment_method": { "id": "visa", "type": "credit_card", "token": "1c87b6b301010101ddcd92f9bbbb3be2", "installments": 1 } } ] } } }, "pix": { "summary": "Pix — Brazil (MLB)", "value": { "type": "online", "processing_mode": "automatic", "total_amount": "100.00", "external_reference": "ORDER-2024-001234", "payer": { "email": "customer@example.com" }, "transactions": { "payments": [ { "amount": "100.00", "expiration_time": "P1D", "payment_method": { "id": "pix", "type": "bank_transfer" } } ] } } }, "boleto": { "summary": "Boleto Bancário — Brazil (MLB)", "value": { "type": "online", "processing_mode": "automatic", "total_amount": "100.00", "external_reference": "ORDER-2024-001234", "payer": { "email": "customer@example.com", "first_name": "João", "last_name": "Silva", "identification": { "type": "CPF", "number": "99999999999" }, "address": { "zip_code": "11034430", "street_name": "Av. Paulista", "street_number": "100", "city": "SAO PAULO", "state": "SP" } }, "transactions": { "payments": [ { "amount": "100.00", "expiration_time": "P1D", "payment_method": { "id": "bolbradesco", "type": "ticket" } } ] } } }, "oxxo": { "summary": "OXXO — Mexico (MLM)", "value": { "type": "online", "processing_mode": "automatic", "total_amount": "500.00", "external_reference": "ORDER-2024-001234", "payer": { "email": "customer@example.com" }, "transactions": { "payments": [ { "amount": "500.00", "expiration_time": "P3D", "payment_method": { "id": "oxxo", "type": "ticket" } } ] } } }, "spei": { "summary": "SPEI — Mexico (MLM)", "value": { "type": "online", "processing_mode": "automatic", "total_amount": "1000.00", "external_reference": "ORDER-2024-001234", "payer": { "email": "customer@example.com" }, "transactions": { "payments": [ { "amount": "1000.00", "expiration_time": "P1D", "payment_method": { "id": "clabe", "type": "bank_transfer" } } ] } } }, "pse": { "summary": "PSE — Colombia (MCO)", "value": { "type": "online", "processing_mode": "automatic", "total_amount": "100000.00", "external_reference": "ORDER-2024-001234", "payer": { "email": "customer@example.com", "entity_type": "individual", "first_name": "Juan", "last_name": "Pérez", "identification": { "type": "NIT", "number": "76262349" } }, "transactions": { "payments": [ { "amount": "100000.00", "expiration_time": "PT20M", "payment_method": { "id": "pse", "type": "bank_transfer", "financial_institution": "1051" } } ] }, "config": { "online": { "callback_url": "https://merchant.com/pse/return" } }, "additional_info": { "payer": { "ip_address": "200.100.50.25" } } } }, "rapipago": { "summary": "Rapipago — Argentina (MLA)", "value": { "type": "online", "processing_mode": "automatic", "capture_mode": "automatic_async", "total_amount": "5000.00", "external_reference": "ORDER-2024-001234", "payer": { "email": "customer@example.com", "identification": { "type": "DNI", "number": "12345678" } }, "transactions": { "payments": [ { "amount": "5000.00", "payment_method": { "id": "rapipago", "type": "ticket" } } ] } } }, "manual_mode": { "summary": "Manual processing mode", "value": { "type": "online", "processing_mode": "manual", "capture_mode": "manual", "total_amount": "100.00", "external_reference": "ORDER-2024-001234", "payer": { "email": "customer@example.com" } } } } } } }, "responses": { "201": { "description": "Order created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "description": "Resource locked — a concurrent request is already processing this order" }, "500": { "description": "Internal server error" } } }, "get": { "operationId": "searchOrders", "summary": "Search orders", "description": "Search for orders using date range and optional filters. begin_date and end_date are required.", "tags": [ "Orders" ], "parameters": [ { "name": "begin_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Start of date range (ISO 8601)" }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "End of date range (ISO 8601)" }, { "name": "external_reference", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "online" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created", "processed", "action_required", "processing", "canceled" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderSearchResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Get order by ID", "description": "Returns all order information for the given order ID.", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order ID" } ], "responses": { "200": { "description": "Order found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/orders/{order_id}/cancel": { "post": { "operationId": "cancelOrder", "summary": "Cancel an order", "description": "Cancels an order and all its transactions. Only orders with status=action_required or status=created can be canceled.", "tags": [ "Orders" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict — order cannot be canceled in its current status" } } } }, "/v1/orders/{order_id}/process": { "post": { "operationId": "processOrder", "summary": "Process an order", "description": "Triggers processing of an order and all its transactions. Only available for manual-mode orders (processing_mode=manual). After calling this endpoint the order transitions to processed or action_required.", "tags": [ "Orders" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order processing triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict — order already processed or cannot be processed in current status" } } } }, "/v1/orders/{order_id}/capture": { "post": { "operationId": "captureOrder", "summary": "Capture an authorized order", "description": "Fully captures a previously authorized order (capture_mode=manual). All associated authorized transactions are captured in full.", "tags": [ "Orders" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order captured", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "status_detail": { "type": "string" }, "transactions": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict — order cannot be captured in its current status" } } } }, "/v1/orders/{order_id}/refund": { "post": { "operationId": "refundOrder", "summary": "Refund an order", "description": "Performs a full or partial refund of transactions associated with an order. For a full refund, send an empty request body (omit transactions). For a partial refund, include the transactions array with the specific transaction IDs and amounts to refund.", "tags": [ "Orders" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRefundRequest" }, "examples": { "full_refund": { "summary": "Full refund", "value": {} }, "partial_refund": { "summary": "Partial refund of specific transaction", "value": { "transactions": [ { "id": "transaction_id_here", "amount": "50.00" } ] } } } } } }, "responses": { "201": { "description": "Refund created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "status_detail": { "type": "string" }, "transactions": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict — order cannot be refunded in its current status" } } } }, "/checkout/preferences": { "post": { "operationId": "createPreference", "summary": "Create a preference", "description": "Creates a Checkout Pro preference. The response contains `init_point` (production) and \n**Webhook events triggered:** payment, merchant_order", "tags": [ "Preferences" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceRequest" }, "examples": { "simple": { "summary": "Simple one-item preference", "value": { "items": [ { "title": "Premium Plan", "quantity": 1, "unit_price": 99.9 } ], "payer": { "email": "customer@example.com" }, "back_urls": { "success": "https://mystore.com/success", "failure": "https://mystore.com/failure", "pending": "https://mystore.com/pending" }, "auto_return": "approved" } } } } } }, "responses": { "201": { "description": "Preference created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preference" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "200": { "description": "Preference created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preference" } } } } } } }, "/checkout/preferences/{id}": { "get": { "operationId": "getPreference", "summary": "Get preference by ID", "tags": [ "Preferences" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Preference found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preference" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "put": { "operationId": "updatePreference", "summary": "Update a preference", "tags": [ "Preferences" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceRequest" } } } }, "responses": { "200": { "description": "Preference updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preference" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/checkout/preferences/search": { "get": { "operationId": "searchPreferences", "summary": "Search preferences", "tags": [ "Preferences" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "external_reference", "in": "query", "schema": { "type": "string" } }, { "name": "marketplace", "in": "query", "schema": { "type": "string" } }, { "name": "site_id", "in": "query", "schema": { "type": "string" } }, { "name": "sponsor_id", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "elements": { "type": "array", "items": { "$ref": "#/components/schemas/Preference" } }, "paging": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/customers": { "post": { "operationId": "createCustomer", "summary": "Create a customer", "description": "Creates a customer profile for storing payment methods. The customer email is unique per account.", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRequest" } } } }, "responses": { "201": { "description": "Customer created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/customers/search": { "get": { "operationId": "searchCustomers", "summary": "Search customers", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "email", "in": "query", "schema": { "type": "string", "format": "email" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSearchResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/customers/{id}": { "get": { "operationId": "getCustomer", "summary": "Get customer by ID", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "put": { "operationId": "updateCustomer", "summary": "Update a customer", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRequest" } } } }, "responses": { "200": { "description": "Customer updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/customers/{customer_id}/cards": { "post": { "operationId": "saveCard", "summary": "Save a card to a customer", "description": "Saves a tokenized card to a customer profile for future payments. The token must be created client-side via MercadoPago.js. Raw card data must never pass through your server.\n**PCI scope:** Handling this endpoint brings your integration into PCI DSS scope.", "tags": [ "Cards" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveCardRequest" } } } }, "responses": { "201": { "description": "Card saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "operationId": "listCards", "summary": "List customer cards", "tags": [ "Cards" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/customers/{customer_id}/cards/{id}": { "get": { "operationId": "getCard", "summary": "Get a saved card", "tags": [ "Cards" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "put": { "operationId": "updateCard", "summary": "Update a saved card", "tags": [ "Cards" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCardRequest" } } } }, "responses": { "200": { "description": "Card updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteCard", "summary": "Delete a saved card", "tags": [ "Cards" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/card_tokens": { "post": { "operationId": "createCardToken", "summary": "Create a card token (client-side only)", "description": "**CLIENT-SIDE ONLY.** Creates a single-use card token from raw card data. Call this from your frontend using MercadoPago.js with the PUBLIC_KEY. Never call this endpoint server-side — doing so puts raw PAN and CVV on your server and brings your integration into full PCI DSS scope.\n**PCI scope:** Handling this endpoint brings your integration into PCI DSS scope.\n**Auth note:** Use PUBLIC_KEY for this endpoint (not ACCESS_TOKEN). Public key is safe in frontend code. Using ACCESS_TOKEN here from the browser exposes your server credentials.", "tags": [ "Cards" ], "security": [ { "publicKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardTokenRequest" } } } }, "responses": { "201": { "description": "Card token created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardToken" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/card_tokens/{id}": { "get": { "operationId": "getCardToken", "summary": "Get a card token", "tags": [ "Cards" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Token found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardToken" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "**PCI scope:** Handling this endpoint brings your integration into PCI DSS scope." } }, "/preapproval_plan": { "post": { "operationId": "createSubscriptionPlan", "summary": "Create a subscription plan", "description": "Creates a recurring billing plan. Individual subscriptions reference this plan. The response includes `init_point` to send subscribers to authorize billing.", "tags": [ "Plans" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanRequest" }, "examples": { "monthly_plan": { "summary": "Monthly plan — R$29.90", "value": { "reason": "Monthly Premium Subscription", "auto_recurring": { "frequency": 1, "frequency_type": "months", "transaction_amount": 29.9, "currency_id": "BRL" } } } } } } }, "responses": { "201": { "description": "Plan created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlan" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" }, "500": { "description": "Internal server error" } } } }, "/preapproval_plan/{id}": { "get": { "operationId": "getSubscriptionPlan", "summary": "Get subscription plan", "tags": [ "Plans" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plan found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlan" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" }, "500": { "description": "Internal server error" } } }, "put": { "operationId": "updateSubscriptionPlan", "summary": "Update a subscription plan", "tags": [ "Plans" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanRequest" } } } }, "responses": { "200": { "description": "Plan updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlan" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" }, "500": { "description": "Internal server error" } } } }, "/preapproval_plan/search": { "get": { "operationId": "searchSubscriptionPlans", "summary": "Search subscription plans", "tags": [ "Plans" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "criteria", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionSearchResult" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/preapproval": { "post": { "operationId": "createSubscription", "summary": "Create a subscription", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionRequest" } } } }, "responses": { "201": { "description": "Subscription created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal server error" } } } }, "/preapproval/{id}": { "get": { "operationId": "getSubscription", "summary": "Get subscription", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscription found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "500": { "description": "Internal server error" } } }, "put": { "operationId": "updateSubscription", "summary": "Update subscription", "description": "Update subscription status or billing details. Common use: `{\"status\": \"paused\"}` to pause, `{\"status\": \"authorized\"}` to resume, `{\"status\": \"cancelled\"}` to cancel.", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdateRequest" } } } }, "responses": { "200": { "description": "Subscription updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/preapproval/search": { "get": { "operationId": "searchSubscriptions", "summary": "Search subscriptions", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "payer_id", "in": "query", "schema": { "type": "integer" } }, { "name": "payer_email", "in": "query", "schema": { "type": "string", "format": "email" } }, { "name": "preapproval_plan_id", "in": "query", "schema": { "type": "string" } }, { "name": "transaction_amount", "in": "query", "schema": { "type": "number" } }, { "name": "semaphore", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "authorized", "paused", "cancelled" ] } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionSearchResult" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/authorized_payments/{id}": { "get": { "operationId": "getAuthorizedPayment", "summary": "Get subscription invoice", "tags": [ "Invoices" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Invoice found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizedPayment" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/v1/chargebacks/{id}": { "get": { "operationId": "getChargeback", "summary": "Get chargeback by ID", "tags": [ "Chargebacks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chargeback found", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "payments": { "type": "array", "items": { "type": "object" } }, "currency": { "type": "string" }, "amount": { "type": "number", "format": "float" }, "coverage_applied": { "type": "boolean" }, "coverage_elegible": { "type": "boolean" }, "documentation_required": { "type": "boolean" }, "documentation_status": { "type": "string", "enum": [ "valid", "invalid", "not_supplied" ] }, "documentation": { "type": "object" }, "date_documentation_deadline": { "type": "string", "format": "date-time" }, "date_created": { "type": "string", "format": "date-time" }, "date_last_updated": { "type": "string", "format": "date-time" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateChargeback", "summary": "Upload chargeback documentation", "tags": [ "Chargebacks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } } } } } }, "responses": { "200": { "description": "Chargeback updated" } } } }, "/merchant_orders": { "post": { "operationId": "createMerchantOrder", "summary": "Create a merchant order", "tags": [ "Merchant Orders" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_reference": { "type": "string" }, "preference_id": { "type": "string" }, "marketplace": { "type": "string" }, "notification_url": { "type": "string", "format": "uri", "deprecated": true }, "sponsor_id": { "type": "integer" }, "payer": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string", "format": "email" } } }, "site_id": { "type": "string", "enum": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, "items": { "type": "array", "items": { "type": "object" } }, "additional_info": { "type": "string" }, "application_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Merchant order created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "opened", "closed", "expired" ] }, "order_status": { "type": "string", "enum": [ "payment_required", "payment_in_process", "paid", "partially_paid", "partially_refunded", "pending_cancel", "cancelled", "refunded" ] }, "external_reference": { "type": "string" }, "preference_id": { "type": "string" }, "marketplace": { "type": "string" }, "application_id": { "type": "string" }, "site_id": { "type": "string", "enum": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, "notification_url": { "type": "string", "format": "uri", "deprecated": true }, "sponsor_id": { "type": "integer" }, "collector": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "nickname": { "type": "string" } } }, "payer": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "nickname": { "type": "string" } } }, "payments": { "type": "array", "items": { "type": "object" } }, "shipments": { "type": "array", "items": { "type": "object" } }, "payouts": { "type": "array", "items": { "type": "object" } }, "items": { "type": "array", "items": { "type": "object" } }, "additional_info": { "type": "string" }, "shipping_cost": { "type": "number", "format": "float" }, "total_amount": { "type": "number", "format": "float" }, "paid_amount": { "type": "number", "format": "float" }, "refunded_amount": { "type": "number", "format": "float" }, "date_created": { "type": "string", "format": "date-time" }, "last_updated": { "type": "string", "format": "date-time" }, "canceled": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "description": "**Webhook events triggered:** merchant_order" } }, "/merchant_orders/{id}": { "get": { "operationId": "getMerchantOrder", "summary": "Get merchant order", "tags": [ "Merchant Orders" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Merchant order found", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "opened", "closed", "expired" ] }, "order_status": { "type": "string", "enum": [ "payment_required", "payment_in_process", "paid", "partially_paid", "partially_refunded", "pending_cancel", "cancelled", "refunded" ] }, "external_reference": { "type": "string" }, "preference_id": { "type": "string" }, "marketplace": { "type": "string" }, "application_id": { "type": "string" }, "site_id": { "type": "string", "enum": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, "notification_url": { "type": "string", "format": "uri", "deprecated": true }, "sponsor_id": { "type": "integer" }, "collector": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "nickname": { "type": "string" } } }, "payer": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "nickname": { "type": "string" } } }, "payments": { "type": "array", "items": { "type": "object" } }, "shipments": { "type": "array", "items": { "type": "object" } }, "payouts": { "type": "array", "items": { "type": "object" } }, "items": { "type": "array", "items": { "type": "object" } }, "additional_info": { "type": "string" }, "shipping_cost": { "type": "number", "format": "float" }, "total_amount": { "type": "number", "format": "float" }, "paid_amount": { "type": "number", "format": "float" }, "refunded_amount": { "type": "number", "format": "float" }, "date_created": { "type": "string", "format": "date-time" }, "last_updated": { "type": "string", "format": "date-time" }, "canceled": { "type": "boolean" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "put": { "operationId": "updateMerchantOrder", "summary": "Update merchant order", "tags": [ "Merchant Orders" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_reference": { "type": "string" }, "preference_id": { "type": "string" }, "marketplace": { "type": "string" }, "notification_url": { "type": "string", "format": "uri", "deprecated": true }, "sponsor_id": { "type": "integer" }, "payer": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string", "format": "email" } } }, "site_id": { "type": "string", "enum": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, "items": { "type": "array", "items": { "type": "object" } }, "additional_info": { "type": "string" }, "application_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Merchant order updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/merchant_orders/search": { "get": { "operationId": "searchMerchantOrders", "summary": "Search merchant orders", "tags": [ "Merchant Orders" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "opened", "closed", "expired" ] } }, { "name": "preference_id", "in": "query", "schema": { "type": "string" } }, { "name": "application_id", "in": "query", "schema": { "type": "string" } }, { "name": "payer_id", "in": "query", "schema": { "type": "integer" } }, { "name": "sponsor_id", "in": "query", "schema": { "type": "integer" } }, { "name": "external_reference", "in": "query", "schema": { "type": "string" } }, { "name": "site_id", "in": "query", "schema": { "type": "string", "enum": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] } }, { "name": "marketplace", "in": "query", "schema": { "type": "string" } }, { "name": "date_created_from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_created_to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "last_updated_from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "last_updated_to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "opened", "closed", "expired" ] }, "order_status": { "type": "string", "enum": [ "payment_required", "payment_in_process", "paid", "partially_paid", "partially_refunded", "pending_cancel", "cancelled", "refunded" ] }, "external_reference": { "type": "string" }, "preference_id": { "type": "string" }, "marketplace": { "type": "string" }, "application_id": { "type": "string" }, "site_id": { "type": "string", "enum": [ "MLA", "MLB", "MLM", "MLC", "MCO", "MPE", "MLU" ] }, "notification_url": { "type": "string", "format": "uri", "deprecated": true }, "sponsor_id": { "type": "integer" }, "collector": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "nickname": { "type": "string" } } }, "payer": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "nickname": { "type": "string" } } }, "payments": { "type": "array", "items": { "type": "object" } }, "shipments": { "type": "array", "items": { "type": "object" } }, "payouts": { "type": "array", "items": { "type": "object" } }, "items": { "type": "array", "items": { "type": "object" } }, "additional_info": { "type": "string" }, "shipping_cost": { "type": "number", "format": "float" }, "total_amount": { "type": "number", "format": "float" }, "paid_amount": { "type": "number", "format": "float" }, "refunded_amount": { "type": "number", "format": "float" }, "date_created": { "type": "string", "format": "date-time" }, "last_updated": { "type": "string", "format": "date-time" }, "canceled": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/oauth/token": { "post": { "operationId": "createOAuthToken", "summary": "Create OAuth token", "description": "Exchanges authorization codes for access tokens, refreshes expired tokens, or requests client credentials tokens for machine-to-machine flows.\n**Security notes:** - The `state` parameter is mandatory for authorization_code flows to prevent CSRF. - Store refresh tokens in server-side encrypted storage — never in localStorage. - Rotate `client_secret` regularly and store in a secrets manager.", "tags": [ "OAuth" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "client_secret", "grant_type" ], "properties": { "client_id": { "type": "string", "description": "Your application's client ID" }, "client_secret": { "type": "string", "description": "Your application's client secret. Never expose in client-side code. Store in a secrets manager." }, "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token", "client_credentials" ], "description": "OAuth 2.0 grant type" }, "code": { "type": "string", "description": "Authorization code from the OAuth redirect (authorization_code flow)" }, "redirect_uri": { "type": "string", "format": "uri", "description": "Must match the registered redirect URI exactly" }, "code_verifier": { "type": "string", "description": "PKCE code verifier (recommended for mobile/SPA)" }, "refresh_token": { "type": "string", "description": "Refresh token for the refresh_token grant" } } }, "examples": { "authorization_code": { "summary": "Exchange authorization code for tokens", "value": { "client_id": "1234567890", "client_secret": "YOUR_CLIENT_SECRET", "grant_type": "authorization_code", "code": "TG-abc123def456", "redirect_uri": "https://myapp.com/oauth/callback" } }, "refresh_token": { "summary": "Refresh an expired access token", "value": { "client_id": "1234567890", "client_secret": "YOUR_CLIENT_SECRET", "grant_type": "refresh_token", "refresh_token": "TG-refresh-token-here" } } } } } }, "responses": { "200": { "description": "Tokens issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Bearer access token for API calls", "example": "APP_USR-1234-mmdd-abcd-xxxxxxxxxxxx" }, "token_type": { "type": "string", "example": "bearer" }, "expires_in": { "type": "integer", "description": "Access token TTL in seconds", "example": 15552000 }, "scope": { "type": "string", "example": "offline_access read write" }, "refresh_token": { "type": "string", "description": "Long-lived token to refresh access_token" }, "user_id": { "type": "integer", "description": "MP user ID of the authorized user" }, "public_key": { "type": "string", "description": "Public key for client-side card tokenization" }, "live_mode": { "type": "boolean", "description": "true = production token." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/payment_methods": { "get": { "operationId": "listPaymentMethods", "summary": "List available payment methods", "description": "Returns all payment methods available for the credential's site_id. Use this to build payment method selectors and validate method availability before attempting a payment.", "tags": [ "Payment Methods" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Payment methods list", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "payment_type_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "deactivated" ] }, "secure_thumbnail": { "type": "string", "format": "uri" }, "thumbnail": { "type": "string", "format": "uri" }, "deferred_capture": { "type": "string", "enum": [ "supported", "unsupported", "does_not_apply" ] }, "settings": { "type": "object", "description": "Card settings (bin ranges, security codes, card length)." }, "additional_info_needed": { "type": "array", "items": { "type": "string" }, "description": "Additional fields required at checkout." }, "min_allowed_amount": { "type": "number", "format": "float" }, "max_allowed_amount": { "type": "number", "format": "float" }, "accreditation_time": { "type": "integer" }, "financial_institutions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" } } } }, "processing_modes": { "type": "array", "items": { "type": "string", "enum": [ "aggregator", "gateway" ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/payment_methods/installments": { "get": { "operationId": "getInstallments", "summary": "Get installment options", "description": "Returns available installment plans for a given card BIN, amount, and site. Use this to populate installment selectors in your checkout.", "tags": [ "Payment Methods" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "payment_method_id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "visa" }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "number", "format": "float" }, "example": 1000.0 }, { "name": "issuer_id", "in": "query", "schema": { "type": "string" } }, { "name": "bin", "in": "query", "schema": { "type": "string" }, "description": "First 6 digits of the card (BIN) for more accurate installment pricing", "example": "411111" } ], "responses": { "200": { "description": "Installment options", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "payment_method_id": { "type": "string" }, "payment_type_id": { "type": "string" }, "issuer": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "payer_costs": { "type": "array", "items": { "type": "object", "properties": { "installments": { "type": "integer" }, "installment_rate": { "type": "number", "format": "float" }, "discount_rate": { "type": "number", "format": "float" }, "reimbursement_rate": { "type": "number", "format": "float" }, "labels": { "type": "array", "items": { "type": "string" } }, "total_amount": { "type": "number", "format": "float" }, "installment_amount": { "type": "number", "format": "float" } } } } } } } } } } } } }, "/v1/identification_types": { "get": { "operationId": "listIdentificationTypes", "summary": "List identification types", "description": "Returns valid ID document types for the credential's site_id. Examples: CPF/CNPJ (Brazil), DNI/CUIL/CUIT (Argentina), RFC/CURP (Mexico). Use this to populate identification type selectors and validate inputs.", "tags": [ "Identification Types" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Identification types list", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "CPF" }, "name": { "type": "string", "example": "CPF" }, "type": { "type": "string", "enum": [ "number", "letter" ] }, "min_length": { "type": "integer" }, "max_length": { "type": "integer" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v2/wallet_connect/agreements": { "post": { "operationId": "createWalletAgreement", "summary": "Create a Wallet Connect agreement", "description": "Creates an authorization agreement for Wallet Connect. Returns an agreement token to redirect the payer to MP for wallet authorization.\n**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)", "tags": [ "Wallet Connect" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "return_uri", "external_flow_id" ], "properties": { "return_uri": { "type": "string", "format": "uri", "description": "URL to redirect user back after authorization." }, "external_flow_id": { "type": "string", "description": "Seller-side flow state identifier." }, "external_user": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" } } }, "agreement_data": { "type": "object", "properties": { "validation_amount": { "type": "number", "format": "float" }, "description": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Agreement created", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement_id": { "type": "string" }, "agreement_uri": { "type": "string", "format": "uri", "description": "Redirect payer to this URL to authorize the agreement" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "parameters": [ { "name": "client.id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "x-platform-id", "in": "header", "required": false, "schema": { "type": "string" } } ] } }, "/v2/wallet_connect/agreements/{agreement_id}": { "get": { "operationId": "getWalletAgreement", "summary": "Get a Wallet Connect agreement", "tags": [ "Wallet Connect" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "agreement_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "client.id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "x-platform-id", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agreement found", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "cancelled", "expired" ] }, "date_created": { "type": "string", "format": "date-time" }, "date_canceled": { "type": "string", "format": "date-time", "nullable": true }, "date_expire": { "type": "string", "format": "date-time" }, "validation_code": { "type": "string" }, "approval_uri": { "type": "string", "format": "uri" }, "redirect_uri": { "type": "string", "format": "uri" }, "external_flow_id": { "type": "string" }, "external_user": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" } } }, "agreement_data": { "type": "object", "properties": { "validation_amount": { "type": "number", "format": "float" }, "description": { "type": "string" } } }, "site_id": { "type": "string", "enum": [ "MLA", "MLB", "MLM" ] }, "application_id": { "type": "string" }, "collector_id": { "type": "integer" }, "model_version": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "Internal server error" } }, "description": "**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)" }, "delete": { "operationId": "deleteWalletAgreement", "summary": "Revoke a Wallet Connect agreement", "tags": [ "Wallet Connect" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "agreement_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "client.id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "x-platform-id", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agreement revoked" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "Internal server error" } }, "description": "**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)" } }, "/v2/wallet_connect/agreements/{agreement_id}/payer_token": { "post": { "operationId": "createWalletPayerToken", "summary": "Create a payer token from agreement", "tags": [ "Wallet Connect" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "agreement_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-platform-id", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Authorization code from the Wallet Connect flow" } } } } } }, "responses": { "200": { "description": "Payer token created", "content": { "application/json": { "schema": { "type": "object", "properties": { "payer_token": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "Internal server error" } }, "description": "**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)" } }, "/v1/payouts": { "post": { "operationId": "createPayout", "summary": "Create a batch of payout transactions", "tags": [ "Payouts" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_reference": { "type": "string" }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency_id": { "$ref": "#/components/schemas/CurrencyId" }, "payment_method_id": { "type": "string" }, "beneficiary": { "type": "object" } } } } } } } } }, "responses": { "201": { "description": "Payout batch created" } }, "description": "**Available in:** Argentina, Mexico (MLA, MLM)" } }, "/v1/payouts/{payout_id}/transactions": { "get": { "operationId": "listPayoutTransactions", "summary": "List payout transactions", "tags": [ "Payouts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "payout_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction list" } }, "description": "**Available in:** Argentina, Mexico (MLA, MLM)" } }, "/v1/payouts/{payout_id}/transactions/{transaction_id}/cancel": { "put": { "operationId": "cancelPayoutTransaction", "summary": "Cancel a payout transaction", "tags": [ "Payouts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "payout_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction cancelled" } }, "description": "**Available in:** Argentina, Mexico (MLA, MLM)" } }, "/v1/transaction-intents/process": { "post": { "operationId": "processTransactionIntent", "summary": "Create a disbursement (Pix or bank transfer)", "description": "Creates a Pix or bank transfer disbursement for Brazil. The `payment_method_id` determines the method: - `pix` — instant Pix transfer (available 24/7) - `bank_transfer` — TED/DOC bank transfer\n**Available in:** Brazil (MLB)", "tags": [ "Payouts" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_reference": { "type": "string" }, "point_of_interaction": { "type": "object", "properties": { "type": { "type": "string" } } }, "transaction": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency_id": { "type": "string", "example": "BRL" }, "receiver": { "type": "object" } } } } }, "examples": { "pix": { "summary": "Pix disbursement — Brazil", "value": { "external_reference": "PAYOUT-001", "point_of_interaction": { "type": "PIX" }, "transaction": { "amount": 100.0, "currency_id": "BRL" } } } } } } }, "responses": { "201": { "description": "Transaction intent created" } } } }, "/v1/transaction-intents/{id}": { "get": { "operationId": "getTransactionIntent", "summary": "Get disbursement status", "tags": [ "Payouts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction intent found" } }, "description": "**Available in:** Brazil (MLB)" } }, "/point/integration-api/devices": { "get": { "operationId": "listPointDevices", "summary": "List Point devices", "tags": [ "Point Deprecated" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Device list", "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "pos_id": { "type": "integer" }, "store_id": { "type": "string" }, "operating_mode": { "type": "string", "enum": [ "PDV", "STANDALONE" ] } } } } } } } } } }, "description": "**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)" } }, "/point/integration-api/devices/{deviceid}/payment-intents": { "post": { "operationId": "createPointPaymentIntent", "summary": "Create a payment intent on a Point device", "description": "Creates a payment intent that is sent to a Point POS device for the customer to tap/insert their card. The device handles card capture.\n**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)\n**Idempotent:** Supports `X-Idempotency-Key` header to safely retry without duplicate charges.\n**Webhook events triggered:** point_integration_wh", "tags": [ "Point Deprecated" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deviceid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "description": "Amount in cents (integer for Point devices)", "example": 1500 }, "description": { "type": "string" }, "payment": { "type": "object", "properties": { "installments": { "type": "integer" }, "type": { "type": "string", "enum": [ "credit_card", "debit_card" ] } } }, "print_on_terminal": { "type": "boolean", "description": "Print receipt on the device after payment" } } } } } }, "responses": { "201": { "description": "Payment intent created and sent to device", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "device_id": { "type": "string" }, "amount": { "type": "integer" }, "status": { "type": "string", "enum": [ "open", "on_terminal", "processing", "processed", "abandoned", "cancelled", "error" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/point/integration-api/devices/{deviceid}/payment-intents/{paymentintentid}": { "delete": { "operationId": "cancelPointPaymentIntent", "summary": "Cancel a payment intent", "tags": [ "Point Deprecated" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deviceid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "paymentintentid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment intent cancelled" } }, "description": "**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)" } }, "/point/integration-api/payment-intents/{paymentintentid}": { "get": { "operationId": "getPointPaymentIntent", "summary": "Get payment intent details", "tags": [ "Point Deprecated" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "paymentintentid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment intent found" } }, "description": "**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)" } }, "/point/integration-api/devices/{deviceid}/refund": { "post": { "operationId": "createPointRefundIntent", "summary": "Create a refund intent on a terminal", "description": "Initiates a refund intent on a Point terminal device.", "tags": [ "Terminals" ], "security": [ { "bearerAuth": [] } ], "x-mp-sites": [ "MLA", "MLB", "MLM" ], "parameters": [ { "name": "deviceid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Terminal device identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payment_id" ], "properties": { "payment_id": { "type": "integer", "description": "ID of the payment to refund" }, "amount": { "type": "number", "format": "double", "description": "Amount to refund (omit for full refund)" } } } } } }, "responses": { "200": { "description": "Refund intent created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Refund intent ID" }, "status": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/point/integration-api/devices/{deviceid}/refund/{refundintentid}": { "delete": { "operationId": "cancelPointRefundIntent", "summary": "Cancel a refund intent on a terminal", "tags": [ "Terminals" ], "security": [ { "bearerAuth": [] } ], "x-mp-sites": [ "MLA", "MLB", "MLM" ], "parameters": [ { "name": "deviceid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "refundintentid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Refund intent cancelled" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/point/integration-api/refund/{refundintentid}": { "get": { "operationId": "getPointRefundIntent", "summary": "Get a refund intent status", "tags": [ "Terminals" ], "security": [ { "bearerAuth": [] } ], "x-mp-sites": [ "MLA", "MLB", "MLM" ], "parameters": [ { "name": "refundintentid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Refund intent identifier" } ], "responses": { "200": { "description": "Refund intent found", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "payment_id": { "type": "integer" }, "amount": { "type": "number" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/instore/qr/seller/collectors/{user_id}/pos/{external_pos_id}/orders": { "get": { "operationId": "getInstoreOrderV2", "summary": "Get in-store order (deprecated V2)", "deprecated": true, "tags": [ "QR Deprecated" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "external_pos_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order found (deprecated)" } }, "description": "**Migration guide:** https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order" }, "delete": { "operationId": "deleteInstoreOrderV2", "summary": "Delete in-store order (deprecated V2)", "deprecated": true, "tags": [ "QR Deprecated" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "external_pos_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order deleted (deprecated)" } }, "description": "**Migration guide:** https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order" } }, "/users/{user_id}/stores": { "post": { "operationId": "createStore", "summary": "Create a store", "tags": [ "Stores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "business_hours": { "type": "object" }, "location": { "type": "object" }, "external_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Store created" } } } }, "/pos": { "get": { "operationId": "searchPOS", "summary": "Search points of sale", "tags": [ "POS" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "external_store_id", "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "POS search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "paging": { "$ref": "#/components/schemas/Pagination" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/POS" } } } } } } } } }, "post": { "operationId": "createPOS", "summary": "Create a point of sale", "description": "Creates a point of sale in a store to receive payments for products or services. Each POS will have a unique QR code linked to it.", "tags": [ "POS" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POSRequest" }, "example": { "name": "Main POS", "fixed_amount": false, "store_id": "1234567", "external_store_id": "SUC001", "external_id": "POS001" } } } }, "responses": { "201": { "description": "POS created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POS" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/pos/{id}": { "get": { "operationId": "getPOS", "summary": "Get a point of sale", "tags": [ "POS" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "POS identifier" } ], "responses": { "200": { "description": "POS found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POS" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updatePOS", "summary": "Update a point of sale", "tags": [ "POS" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POSRequest" } } } }, "responses": { "200": { "description": "POS updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POS" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deletePOS", "summary": "Delete a point of sale", "tags": [ "POS" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "POS identifier to delete" } ], "responses": { "200": { "description": "POS deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/users/{user_id}/pos": { "get": { "operationId": "listPOS", "summary": "List POS devices for a user", "tags": [ "POS" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "POS list" } } } }, "/v1/payments/{id}/cancellations": { "put": { "operationId": "cancelPayment", "summary": "Cancel a payment", "description": "Cancels a payment that is in `pending` or `authorized` status. Only payments that have not yet been captured or processed can be cancelled. For approved payments use the refunds endpoint instead.", "tags": [ "Cancellations & Refunds" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Payment ID to cancel" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "cancelled" ], "description": "Must be \"cancelled\"" } } } } } }, "responses": { "200": { "description": "Payment cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/customers/{id}/delete": { "delete": { "operationId": "deleteCustomer", "summary": "Delete a customer", "description": "Permanently deletes a customer profile. This action cannot be undone. Saved cards associated with the customer will also be removed.", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Customer ID to delete" } ], "responses": { "200": { "description": "Customer deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/customers/{customer_id}/addresses": { "post": { "operationId": "createCustomerAddress", "summary": "Create a customer address", "description": "Adds a shipping or billing address to a customer profile.", "tags": [ "Addresses" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" }, "example": { "zip_code": "01310-100", "street_name": "Av. Paulista", "street_number": "1000", "city": "São Paulo", "state": "SP" } } } }, "responses": { "201": { "description": "Address created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "operationId": "listCustomerAddresses", "summary": "List customer addresses", "tags": [ "Addresses" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Address list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/customers/{customer_id}/addresses/{address_id}": { "get": { "operationId": "getCustomerAddress", "summary": "Get a customer address", "tags": [ "Addresses" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Address found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateCustomerAddress", "summary": "Update a customer address", "tags": [ "Addresses" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } }, "responses": { "200": { "description": "Address updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteCustomerAddress", "summary": "Delete a customer address", "tags": [ "Addresses" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Address deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/preapproval/export": { "get": { "operationId": "exportSubscriptions", "summary": "Export subscriptions", "description": "Exports a list of subscriptions for a collector as a downloadable file. Filter by plan ID, status, and sort order.", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "collector_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Collector (seller) user ID" }, { "name": "preapproval_plan_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by plan ID" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "authorized", "paused", "cancelled" ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "date_created", "last_modified" ], "default": "date_created" } } ], "responses": { "200": { "description": "Export file", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/authorized_payments": { "get": { "operationId": "searchAuthorizedPayments", "summary": "Search subscription invoices", "description": "Search billing invoices generated by subscriptions.", "tags": [ "Invoices" ], "parameters": [ { "name": "preapproval_id", "in": "query", "schema": { "type": "string" } }, { "name": "payment_id", "in": "query", "schema": { "type": "integer" } }, { "name": "payer_id", "in": "query", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "scheduled", "processed", "recycling", "cancelled" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizedPaymentSearchResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/terminals/v1/list": { "get": { "operationId": "listTerminals", "summary": "Get list of terminals", "description": "Returns all Point hardware terminals registered to the account.\n**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)", "tags": [ "Terminals" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Terminal list", "content": { "application/json": { "schema": { "type": "object", "properties": { "terminals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "pos_id": { "type": "integer" }, "store_id": { "type": "string" }, "operating_mode": { "type": "string", "enum": [ "PDV", "STANDALONE" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/terminals/v1/setup": { "patch": { "operationId": "updateTerminalOperationMode", "summary": "Update terminal operation mode", "description": "Changes the operating mode of one or more terminals. PDV — integrated POS mode (connected to your system); STANDALONE — independent mode (no system integration).\n**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)", "tags": [ "Terminals" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "terminals" ], "properties": { "terminals": { "type": "array", "items": { "type": "object", "required": [ "id", "operating_mode" ], "properties": { "id": { "type": "string", "description": "Terminal ID" }, "operating_mode": { "type": "string", "enum": [ "PDV", "STANDALONE" ] } } } } } } } } }, "responses": { "200": { "description": "Operation mode updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/terminals/v1/actions": { "post": { "operationId": "createTerminalAction", "summary": "Create a terminal print action", "description": "Sends a print action to a Point terminal — either a receipt image or a DTE (electronic tax document, available in Chile/MLC only). Set `type` to `PRINT_INFO` for image printing or `PRINT_DTE` for DTE.\n**Available in:** Argentina, Brazil, Chile, Mexico (MLA, MLB, MLC, MLM)", "tags": [ "Terminals" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "external_reference", "config", "content" ], "properties": { "type": { "type": "string", "enum": [ "PRINT_INFO", "PRINT_DTE" ], "description": "PRINT_INFO — print a custom image or receipt; PRINT_DTE — print a DTE document (MLC only)" }, "external_reference": { "type": "string", "description": "Your reference ID for this print job" }, "config": { "type": "object", "description": "Target terminal configuration", "properties": { "device_id": { "type": "string", "description": "Terminal device ID" } } }, "content": { "type": "object", "description": "Print content (varies by type)", "properties": { "source": { "type": "string", "format": "uri", "description": "URL of image to print (PRINT_INFO)" }, "dte_data": { "type": "string", "description": "Base64-encoded DTE XML (PRINT_DTE, MLC only)" } } } } } } } }, "responses": { "200": { "description": "Print action created and sent to terminal", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "sent", "printed", "failed" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/terminals/v1/actions/{action_id}": { "get": { "operationId": "getTerminalAction", "summary": "Get terminal action status", "tags": [ "Terminals" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Action found", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "sent", "printed", "failed" ] }, "external_reference": { "type": "string" }, "date_created": { "type": "string", "format": "date-time" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "**Available in:** Argentina, Brazil, Chile, Mexico (MLA, MLB, MLC, MLM)" } }, "/terminals/v1/actions/{action_id}/cancel": { "post": { "operationId": "cancelTerminalAction", "summary": "Cancel a terminal action", "tags": [ "Terminals" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Action cancelled" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "**Available in:** Argentina, Brazil, Chile, Mexico (MLA, MLB, MLC, MLM)" } }, "/stores/{id}": { "get": { "operationId": "getStore", "summary": "Get store by ID", "tags": [ "Stores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Store ID" } ], "responses": { "200": { "description": "Store found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Store" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/users/{user_id}/stores/search": { "get": { "operationId": "searchStores", "summary": "Search stores", "tags": [ "Stores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by your external store ID" } ], "responses": { "200": { "description": "Store search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "paging": { "$ref": "#/components/schemas/Pagination" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } } } } } } } } } }, "/users/{user_id}/stores/{id}": { "put": { "operationId": "updateStore", "summary": "Update a store", "tags": [ "Stores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreRequest" } } } }, "responses": { "200": { "description": "Store updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Store" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteStore", "summary": "Delete a store", "tags": [ "Stores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Store deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/instore/integrator": { "patch": { "operationId": "createQRIntegratorConfig", "summary": "Create or update QR integrator configuration", "description": "Configures the integrator settings for QR in-store payments.", "tags": [ "QR Integrator" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback_url": { "type": "string", "format": "uri", "description": "Webhook URL for QR payment events" }, "notification_url": { "type": "string", "format": "uri", "deprecated": true } } } } } }, "responses": { "200": { "description": "Integrator config updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "operationId": "getQRIntegratorConfig", "summary": "Get QR integrator configuration", "tags": [ "QR Integrator" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Integrator config", "content": { "application/json": { "schema": { "type": "object", "properties": { "callback_url": { "type": "string", "format": "uri" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/instore/orders/{merchant_order_id}/confirmation": { "post": { "operationId": "confirmCashoutQR", "summary": "Confirm QR cashout status", "description": "Confirms the cashout status for a QR-based cash withdrawal order.\n**Available in:** Argentina, Brazil (MLA, MLB)", "tags": [ "QR Orders" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchant_order_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "confirmed", "cancelled" ] } } } } } }, "responses": { "200": { "description": "Cashout confirmed" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mpmobile/instore/qr/{user_id}/{external_id}": { "put": { "operationId": "createInstoreOrderV1", "summary": "Create in-store order (deprecated V1)", "deprecated": true, "tags": [ "QR Deprecated" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Order created (deprecated)" } }, "description": "**Migration guide:** https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order" }, "delete": { "operationId": "deleteInstoreOrderV1", "summary": "Delete in-store order (deprecated V1)", "deprecated": true, "tags": [ "QR Deprecated" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order deleted (deprecated)" } }, "description": "**Migration guide:** https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order" } }, "/instore/qr/seller/collectors/{user_id}/stores/{external_store_id}/pos/{external_pos_id}/orders": { "put": { "operationId": "createInstoreOrderV2", "summary": "Create in-store order (deprecated V2)", "deprecated": true, "tags": [ "QR Deprecated" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "external_store_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "external_pos_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Order created (deprecated)" } }, "description": "**Migration guide:** https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order" } }, "/instore/orders/qr/seller/collectors/{user_id}/pos/{external_pos_id}/qrs": { "post": { "operationId": "createQRTrammaDynamic", "summary": "Create a QR trama (deprecated Dynamic QR)", "deprecated": true, "tags": [ "QR Deprecated" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "external_pos_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "QR trama created (deprecated)" } }, "description": "**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)\n**Migration guide:** https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order" }, "put": { "operationId": "createDynamicQROrder", "summary": "Create dynamic QR order (deprecated)", "deprecated": true, "tags": [ "QR Deprecated" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "external_pos_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Dynamic QR order created (deprecated)" } }, "description": "**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)\n**Migration guide:** https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order" } }, "/post-purchase/v1/claims/{claim_id}": { "get": { "operationId": "getClaim", "summary": "Get claim details", "description": "Returns full details of a post-sale claim including status, stage, and players.", "tags": [ "Claims" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Claim found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claim" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/post-purchase/v1/claims/search": { "get": { "operationId": "searchClaims", "summary": "Search claims", "tags": [ "Claims" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": "integer" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "mediations", "claims" ] } }, { "name": "stage", "in": "query", "schema": { "type": "string", "enum": [ "claim", "dispute", "resolution" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "opened", "closed", "cancelled" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Claims search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimSearchResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/post-purchase/v1/claims/reasons/{reason_id}": { "get": { "operationId": "getClaimReasons", "summary": "Get claim reason", "description": "Returns the description and metadata for a specific claim reason code.", "tags": [ "Claims" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "reason_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reason found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimReason" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/post-purchase/v1/claims/{claim_id}/status_history": { "get": { "operationId": "getClaimHistory", "summary": "Get claim status history", "tags": [ "Claims" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "History entries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimHistoryEntry" } } } } } } } }, "/post-purchase/v1/claims/{claim_id}/evidences": { "get": { "operationId": "getClaimEvidence", "summary": "Get claim evidence", "tags": [ "Claims" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Evidence list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimEvidence" } } } } } } } }, "/post-purchase/v1/claims/{claim_id}/messages": { "get": { "operationId": "getClaimMessages", "summary": "Get claim messages", "tags": [ "Claim Messages" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Message thread", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimMessage" } } } } } } } }, "/post-purchase/v1/claims/{claim_id}/actions/send-message": { "post": { "operationId": "sendClaimMessage", "summary": "Send a message in a claim", "description": "Sends a text message (with optional attachments) in the claim thread.", "tags": [ "Claim Messages" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "application_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "responses": { "201": { "description": "Message sent" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/post-purchase/v1/claims/{claim_id}/attachments": { "post": { "operationId": "attachClaimFile", "summary": "Attach a file to a claim message", "description": "Uploads and attaches a file (image, PDF) to a claim. Supported formats: JPEG, PNG, PDF. Max size: 10 MB.", "tags": [ "Claim Messages" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "File to attach (JPEG, PNG, or PDF, max 10 MB)" } } } } } }, "responses": { "201": { "description": "File attached", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_id": { "type": "string" }, "file_name": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/post-purchase/v1/claims/{claim_id}/attachments/{fileName}": { "get": { "operationId": "getClaimFile", "summary": "Get attached file metadata", "tags": [ "Claim Messages" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fileName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string" }, "file_id": { "type": "string" }, "content_type": { "type": "string" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/post-purchase/v1/claims/{claim_id}/attachments/{fileName}/download": { "get": { "operationId": "downloadClaimFile", "summary": "Download an attached file", "tags": [ "Claim Messages" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fileName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File content", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/post-purchase/v1/claims/{claim_id}/actions/open-dispute": { "post": { "operationId": "requestClaimMediation", "summary": "Request claim mediation", "description": "Escalates a claim to mediation, requesting MP to intervene in the dispute.", "tags": [ "Claim Resolutions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Mediation requested" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/post-purchase/v1/claims/{claim_id}/expected-resolutions": { "get": { "operationId": "getClaimMediationResolutions", "summary": "Get expected mediation resolutions", "description": "Returns the possible resolution options for a claim at the mediation stage.", "tags": [ "Claim Resolutions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Expected resolutions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MediationResolution" } } } } } } } }, "/post-purchase/v1/claims/{claim_id}/actions/evidences": { "post": { "operationId": "uploadShippingEvidence", "summary": "Upload shipping evidence", "description": "Uploads shipping evidence (tracking code, proof of delivery) to support the seller's case in a claim. Accepted as part of the claims resolution process.", "tags": [ "Claim Shipping" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tracking_code", "proof_of_delivery" ] }, "value": { "type": "string", "description": "Tracking code or delivery confirmation reference" } } } } } }, "responses": { "201": { "description": "Shipping evidence uploaded" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/account/release_report/config": { "post": { "operationId": "createReleaseReportConfig", "summary": "Create releases report configuration", "description": "Creates the configuration for automatic releases report generation. Defines columns, schedule frequency, file format, and optional SFTP delivery.", "tags": [ "Releases Report" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportConfig" } } } }, "responses": { "200": { "description": "Configuration created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportConfig" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "operationId": "updateReleaseReportConfig", "summary": "Update releases report configuration", "tags": [ "Releases Report" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportConfig" } } } }, "responses": { "200": { "description": "Configuration updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportConfig" } } } } } }, "get": { "operationId": "getReleaseReportConfig", "summary": "Get releases report configuration", "tags": [ "Releases Report" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportConfig" } } } } } } }, "/v1/account/release_report": { "post": { "operationId": "createReleaseReport", "summary": "Create a releases report", "description": "Generates a one-time releases report for the specified date range. Returns a task ID to poll for completion via the task endpoint.", "tags": [ "Releases Report" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRequest" } } } }, "responses": { "202": { "description": "Report generation started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTask" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "operationId": "getReleaseReport", "summary": "Get releases report list", "tags": [ "Releases Report" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Report list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportListResult" } } } } } } }, "/v1/account/release_report/search": { "get": { "operationId": "searchReleaseReports", "summary": "Search releases reports", "tags": [ "Releases Report" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin_date", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Matching reports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportListResult" } } } } } } }, "/v1/account/release_report/task/{task_id}": { "get": { "operationId": "getReleaseReportTask", "summary": "Get releases report task status", "description": "Polls the status of a report generation task. Check until `status=done`.", "tags": [ "Releases Report" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTask" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/release_report/schedule": { "post": { "operationId": "enableReleaseReportSchedule", "summary": "Enable automatic releases report generation", "description": "Enables scheduled report generation based on the configured frequency.", "tags": [ "Releases Report" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Schedule enabled" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "operationId": "disableReleaseReportSchedule", "summary": "Disable automatic releases report generation", "tags": [ "Releases Report" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Schedule disabled" } } } }, "/v1/account/release_report/list": { "get": { "operationId": "listScheduledReleaseReports", "summary": "List scheduled releases reports", "tags": [ "Releases Report" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Scheduled report list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportListResult" } } } } } } }, "/v1/account/release_report/{file_name}": { "get": { "operationId": "downloadReleaseReport", "summary": "Download a releases report file", "description": "Downloads the generated report CSV file by filename.", "tags": [ "Releases Report" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "file_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "releases_report_2024-01-01_2024-01-31.csv" } ], "responses": { "200": { "description": "Report file", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/settlement_report/config": { "post": { "operationId": "createSettlementReportConfig", "summary": "Create settlements report configuration", "description": "Creates the configuration for automatic all-transactions (settlements) report generation. Defines columns, schedule frequency, file format, and optional SFTP delivery.", "tags": [ "Settlements Report" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportConfig" } } } }, "responses": { "200": { "description": "Configuration created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportConfig" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "operationId": "updateSettlementReportConfig", "summary": "Update settlements report configuration", "tags": [ "Settlements Report" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportConfig" } } } }, "responses": { "200": { "description": "Configuration updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportConfig" } } } } } }, "get": { "operationId": "getSettlementReportConfig", "summary": "Get settlements report configuration", "tags": [ "Settlements Report" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportConfig" } } } } } } }, "/v1/account/settlement_report": { "post": { "operationId": "createSettlementReport", "summary": "Create a settlements report", "description": "Generates a one-time all-transactions report for the specified date range. Returns a task ID to poll for completion.", "tags": [ "Settlements Report" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRequest" } } } }, "responses": { "202": { "description": "Report generation started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTask" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "operationId": "getSettlementReport", "summary": "Get settlements report list", "tags": [ "Settlements Report" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Report list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportListResult" } } } } } } }, "/v1/account/settlement_report/search": { "get": { "operationId": "searchSettlementReports", "summary": "Search settlements reports", "tags": [ "Settlements Report" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin_date", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Matching reports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportListResult" } } } } } } }, "/v1/account/settlement_report/task/{task_id}": { "get": { "operationId": "getSettlementReportTask", "summary": "Get settlements report task status", "tags": [ "Settlements Report" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTask" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/settlement_report/schedule": { "post": { "operationId": "enableSettlementReportSchedule", "summary": "Enable automatic settlements report generation", "tags": [ "Settlements Report" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Schedule enabled" } } }, "delete": { "operationId": "disableSettlementReportSchedule", "summary": "Disable automatic settlements report generation", "tags": [ "Settlements Report" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Schedule disabled" } } } }, "/v1/account/settlement_report/list": { "get": { "operationId": "listScheduledSettlementReports", "summary": "List scheduled settlements reports", "tags": [ "Settlements Report" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Scheduled report list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportListResult" } } } } } } }, "/v1/account/settlement_report/{file_name}": { "get": { "operationId": "downloadSettlementReport", "summary": "Download a settlements report file", "tags": [ "Settlements Report" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "file_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report file", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/orders/{order_id}/transactions/{transaction_id}": { "put": { "operationId": "updateOrderTransaction", "summary": "Update a transaction on an order", "description": "Updates the payment method of a pending transaction on a manual-mode order.", "tags": [ "Orders" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_method": { "$ref": "#/components/schemas/OrderPaymentMethod" } } } } } }, "responses": { "200": { "description": "Transaction updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderTransactionPayment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteOrderTransaction", "summary": "Delete a transaction from an order", "description": "Removes a transaction from a manual-mode order. Only available before processing.", "tags": [ "Orders" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Transaction deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/orders/{order_id}/transactions": { "post": { "operationId": "addOrderTransaction", "summary": "Add a transaction to an order", "description": "Adds a payment transaction to an order. Only available when processing_mode=manual. The order must be in status=created.", "tags": [ "Orders" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payments" ], "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/OrderPayment" } } } } } } }, "responses": { "201": { "description": "Transaction added", "content": { "application/json": { "schema": { "type": "object", "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/OrderTransactionPayment" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/v1/advanced_payments": { "post": { "operationId": "createAdvancedPayment", "summary": "Create an advanced payment", "description": "Creates a Wallet Connect advanced payment (marketplace split payment).\n\n**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)", "tags": [ "Wallet Connect" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Meli-Session-Id", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet_payment": { "type": "object", "properties": { "transaction_amount": { "type": "number", "format": "float" }, "description": { "type": "string" }, "external_reference": { "type": "string" }, "statement_descriptor": { "type": "string" } } }, "payer": { "type": "object", "properties": { "token": { "type": "string" }, "type_token": { "type": "string" } } }, "binary_mode": { "type": "boolean" }, "capture": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Advanced payment created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "payments": { "type": "array", "items": { "type": "object" } }, "wallet_payment": { "type": "object", "properties": { "transaction_amount": { "type": "number", "format": "float" }, "description": { "type": "string" }, "external_reference": { "type": "string" } } }, "disbursements": { "type": "array", "items": { "type": "object" } }, "payer": { "type": "object", "properties": { "token": { "type": "string" }, "type_token": { "type": "string" } } }, "site_id": { "type": "string" }, "binary_mode": { "type": "boolean" }, "date_created": { "type": "string", "format": "date-time" }, "date_last_updated": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/v1/advanced_payments/{advanced_payment_id}": { "get": { "operationId": "getAdvancedPayment", "summary": "Get an advanced payment", "description": "**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)", "tags": [ "Wallet Connect" ], "parameters": [ { "name": "advanced_payment_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Advanced payment found", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "payments": { "type": "array", "items": { "type": "object" } }, "wallet_payment": { "type": "object", "properties": { "transaction_amount": { "type": "number", "format": "float" }, "description": { "type": "string" }, "external_reference": { "type": "string" } } }, "disbursements": { "type": "array", "items": { "type": "object" } }, "payer": { "type": "object", "properties": { "token": { "type": "string" }, "type_token": { "type": "string" } } }, "site_id": { "type": "string" }, "binary_mode": { "type": "boolean" }, "date_created": { "type": "string", "format": "date-time" }, "date_last_updated": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "Internal server error" } } }, "put": { "operationId": "updateAdvancedPayment", "summary": "Capture or cancel an advanced payment", "description": "Capture (capture=true) or cancel (status=cancelled).\n\n**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)", "tags": [ "Wallet Connect" ], "parameters": [ { "name": "advanced_payment_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capture": { "type": "boolean" }, "status": { "type": "string", "enum": [ "cancelled" ] }, "wallet_payment": { "type": "object", "properties": { "transaction_amount": { "type": "number", "format": "float" }, "description": { "type": "string" }, "external_reference": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Advanced payment updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "payments": { "type": "array", "items": { "type": "object" } }, "wallet_payment": { "type": "object", "properties": { "transaction_amount": { "type": "number", "format": "float" }, "description": { "type": "string" }, "external_reference": { "type": "string" } } }, "disbursements": { "type": "array", "items": { "type": "object" } }, "payer": { "type": "object", "properties": { "token": { "type": "string" }, "type_token": { "type": "string" } } }, "site_id": { "type": "string" }, "binary_mode": { "type": "boolean" }, "date_created": { "type": "string", "format": "date-time" }, "date_last_updated": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "Internal server error" } } } }, "/v2/wallet_connect/discounts": { "post": { "operationId": "createWalletDiscount", "summary": "Create a discount promise", "description": "Validates a coupon and returns discount amount and legal terms.\n\n**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)", "tags": [ "Wallet Connect" ], "parameters": [ { "name": "x-payer-token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Payer wallet token from agreement flow." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "coupon", "amount" ], "properties": { "coupon": { "type": "string" }, "amount": { "type": "number", "format": "float" } } } } } }, "responses": { "200": { "description": "Discount promise created", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_amount": { "type": "number", "format": "float" }, "currency_id": { "$ref": "#/components/schemas/CurrencyId" }, "legal_terms": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "type": { "type": "string" }, "coupon_id": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/v2/wallet_connect/coupons": { "post": { "operationId": "validateWalletCoupon", "summary": "Validate a coupon", "description": "Checks coupon status and returns description and legal terms.\n\n**Available in:** Argentina, Brazil, Mexico (MLA, MLB, MLM)", "tags": [ "Wallet Connect" ], "parameters": [ { "name": "x-payer-token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Coupon validated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "inactive", "expired" ] }, "description": { "type": "string" }, "legal_terms": { "type": "string" }, "detail": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Internal server error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Access token. Send in Authorization header only — never as a URL query parameter." }, "publicKey": { "type": "apiKey", "in": "header", "name": "X-Public-Key", "description": "Public key for client-side card tokenization via MercadoPago.js only. Never use for server-side calls." }, "mercadopagoOAuth": { "type": "oauth2", "description": "OAuth 2.0 authorization_code flow for marketplace on-behalf-of and Wallet Connect integrations. For client_credentials and refresh_token, use POST /oauth/token directly with the appropriate grant_type.", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.mercadopago.com/authorization", "tokenUrl": "https://api.mercadopago.com/oauth/token", "scopes": { "read": "Read access to account data", "write": "Write access (create payments, orders)", "offline_access": "Issue refresh tokens for long-lived access" } } } } }, "responses": { "BadRequest": { "description": "Bad request — validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnprocessableEntity": { "description": "Business rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Rate limit exceeded — wait before retrying", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying this request" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 429, "error": "too_many_requests", "message": "Rate limit exceeded. Retry after the indicated number of seconds." } } } } }, "schemas": { "PreferenceRequest": { "type": "object", "required": [ "items" ], "description": "Request body to create a Checkout Pro preference. The preference generates a hosted checkout URL (init_point) where the payer is redirected to complete payment on MP's UI. Use this for simple integrations; use Orders API for custom checkout experiences.", "properties": { "items": { "type": "array", "description": "List of products/services being purchased", "items": { "$ref": "#/components/schemas/PreferenceItem" }, "minItems": 1 }, "payer": { "$ref": "#/components/schemas/PreferencePayer" }, "payment_methods": { "$ref": "#/components/schemas/PreferencePaymentMethods" }, "shipments": { "$ref": "#/components/schemas/PreferenceShipments" }, "back_urls": { "$ref": "#/components/schemas/PreferenceBackUrls" }, "notification_url": { "type": "string", "format": "uri", "description": "URL for IPN notifications. DEPRECATED — use Webhooks instead.", "deprecated": true }, "statement_descriptor": { "type": "string", "description": "Text on the payer's card statement. Max 22 chars.", "maxLength": 22 }, "additional_info": { "type": "string", "description": "Free-text additional info (returned in webhook notifications)" }, "auto_return": { "type": "string", "enum": [ "approved", "all" ], "description": "approved — auto-redirect to success URL on approved payments; all — auto-redirect for any final status." }, "external_reference": { "type": "string", "description": "Your internal order reference. Returned in webhook payloads.", "example": "ORDER-2024-001234" }, "expires": { "type": "boolean", "description": "Whether this preference has an expiry window", "default": false }, "expiration_date_from": { "type": "string", "format": "date-time", "description": "Preference activation start time (ISO 8601)" }, "expiration_date_to": { "type": "string", "format": "date-time", "description": "Preference expiration time (ISO 8601)" }, "marketplace": { "type": "string", "description": "Marketplace identifier" }, "marketplace_fee": { "type": "number", "format": "float", "description": "Marketplace fee charged to the seller" }, "differential_pricing": { "type": "object", "properties": { "id": { "type": "integer" } } }, "binary_mode": { "type": "boolean", "default": false } } }, "PreferenceItem": { "type": "object", "required": [ "title", "quantity", "unit_price" ], "properties": { "id": { "type": "string" }, "title": { "type": "string", "example": "Premium Plan" }, "description": { "type": "string" }, "picture_url": { "type": "string", "format": "uri" }, "category_id": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "example": 1 }, "currency_id": { "$ref": "#/components/schemas/CurrencyId" }, "unit_price": { "type": "number", "format": "float", "description": "Unit price as a decimal (not integer cents)", "example": 99.9 } } }, "PreferencePayer": { "type": "object", "properties": { "name": { "type": "string" }, "surname": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "$ref": "#/components/schemas/Phone" }, "identification": { "$ref": "#/components/schemas/Identification" }, "address": { "$ref": "#/components/schemas/Address" }, "date_created": { "type": "string", "format": "date-time" } } }, "PreferencePaymentMethods": { "type": "object", "properties": { "excluded_payment_methods": { "type": "array", "description": "Payment methods to hide from checkout UI", "items": { "type": "object", "properties": { "id": { "type": "string" } } } }, "excluded_payment_types": { "type": "array", "description": "Payment type groups to exclude", "items": { "type": "object", "properties": { "id": { "type": "string" } } } }, "installments": { "type": "integer", "description": "Maximum number of installments to offer", "example": 12 }, "default_installments": { "type": "integer", "description": "Pre-selected installments in the UI" } } }, "PreferenceShipments": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "custom", "me2", "not_specified" ] }, "free_shipping": { "type": "boolean", "default": false }, "receiver_address": { "$ref": "#/components/schemas/Address" }, "cost": { "type": "number", "format": "float" } } }, "PreferenceBackUrls": { "type": "object", "description": "Redirect URLs after checkout completion. Configure auto_return to control when automatic redirects happen.", "properties": { "success": { "type": "string", "format": "uri", "description": "Redirect after approved payment" }, "pending": { "type": "string", "format": "uri", "description": "Redirect for pending payments (e.g., Boleto)" }, "failure": { "type": "string", "format": "uri", "description": "Redirect after rejected payment" } } }, "Preference": { "type": "object", "description": "A created Checkout Pro preference", "properties": { "id": { "type": "string", "description": "Preference unique identifier", "example": "123456789-abcd1234-ef56-7890-abcd-ef1234567890" }, "init_point": { "type": "string", "format": "uri", "description": "Production checkout URL. Redirect your payer here to complete payment.", "example": "https://www.mercadopago.com.br/checkout/v1/redirect?pref_id=..." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PreferenceItem" } }, "payer": { "$ref": "#/components/schemas/PreferencePayer" }, "payment_methods": { "$ref": "#/components/schemas/PreferencePaymentMethods" }, "back_urls": { "$ref": "#/components/schemas/PreferenceBackUrls" }, "external_reference": { "type": "string" }, "date_created": { "type": "string", "format": "date-time" }, "last_updated": { "type": "string", "format": "date-time" }, "total_amount": { "type": "number", "format": "float" }, "expires": { "type": "boolean" }, "expiration_date_from": { "type": "string", "format": "date-time" }, "expiration_date_to": { "type": "string", "format": "date-time" }, "collector_id": { "type": "integer" }, "client_id": { "type": "string" }, "marketplace": { "type": "string" }, "marketplace_fee": { "type": "number", "format": "float" } } }, "Claim": { "type": "object", "description": "A post-sale claim (dispute) between buyer and seller", "properties": { "id": { "type": "integer", "description": "Claim unique identifier", "example": 4567890123 }, "type": { "type": "string", "enum": [ "mediations", "claims" ], "description": "mediations — buyer-initiated dispute requiring MP mediation; claims — seller-initiated claim" }, "stage": { "type": "string", "enum": [ "claim", "dispute", "resolution" ], "description": "Current stage in the dispute lifecycle" }, "status": { "type": "string", "enum": [ "opened", "closed", "cancelled" ] }, "date_created": { "type": "string", "format": "date-time" }, "last_updated": { "type": "string", "format": "date-time" }, "resource": { "type": "string", "enum": [ "payment", "shipment", "order" ], "description": "Resource type the claim is about" }, "reason_id": { "type": "string", "description": "Reason code for the claim" }, "players": { "type": "array", "description": "Parties involved (buyer, seller)", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "complainant", "respondent" ] }, "user_id": { "type": "integer" }, "available_actions": { "type": "array", "items": { "type": "string" } } } } } } }, "ClaimMessage": { "type": "object", "description": "A message within a claim thread", "properties": { "id": { "type": "integer" }, "date_created": { "type": "string", "format": "date-time" }, "from": { "type": "object", "properties": { "user_id": { "type": "integer" }, "role": { "type": "string", "enum": [ "complainant", "respondent", "mediator" ] } } }, "message": { "type": "string", "description": "Text content of the message" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string" }, "file_id": { "type": "string" } } } } } }, "ClaimReason": { "type": "object", "description": "A reason code for opening a claim", "properties": { "id": { "type": "string", "example": "PNR" }, "description": { "type": "string", "example": "Product not received" }, "type": { "type": "string", "enum": [ "mediations", "claims" ] } } }, "ClaimSearchResult": { "type": "object", "properties": { "paging": { "$ref": "#/components/schemas/Pagination" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } } } }, "ClaimHistoryEntry": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "stage": { "type": "string" }, "changed_by": { "type": "string", "enum": [ "buyer", "seller", "system", "mediator" ] } } }, "ClaimEvidence": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "tracking_code", "photo", "invoice", "other" ] }, "date_created": { "type": "string", "format": "date-time" }, "file_name": { "type": "string" } } }, "MediationResolution": { "type": "object", "description": "Expected resolution options at mediation stage", "properties": { "type": { "type": "string", "enum": [ "refund", "return", "partial_refund" ] }, "amount": { "type": "number", "format": "float" }, "reason": { "type": "string" } } }, "SendMessageRequest": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Text content of the message to send", "example": "I can provide the tracking code for the shipment." }, "attachments": { "type": "array", "description": "File IDs to attach (upload first via attachments endpoint)", "items": { "type": "string" } } } }, "Error": { "type": "object", "required": [ "status", "error", "message" ], "properties": { "status": { "type": "integer", "description": "HTTP status code", "example": 400 }, "error": { "type": "string", "description": "Error code identifier", "example": "bad_request" }, "message": { "type": "string", "description": "Human-readable error message (English)", "example": "The access token is invalid" }, "cause": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorCause" } } } }, "ErrorCause": { "type": "object", "properties": { "code": { "type": "integer", "example": 2001 }, "description": { "type": "string", "example": "Invalid access token" }, "data": { "type": "string", "nullable": true } } }, "Money": { "type": "object", "description": "Monetary amount. MercadoPago uses decimal amounts (e.g., 100.50 for R$100,50), NOT integer cents. Precision: 2 decimal places for most currencies; 0 for CLP.", "properties": { "amount": { "type": "number", "format": "float", "example": 100.5 }, "currency_id": { "$ref": "#/components/schemas/CurrencyId" } } }, "CurrencyId": { "type": "string", "description": "ISO 4217 currency code for the applicable site", "enum": [ "ARS", "BRL", "MXN", "CLP", "COP", "PEN", "UYU", "BOB", "PYG", "USD", "CRC", "DOP", "HNL", "NIO", "GTQ", "VES" ], "example": "BRL" }, "Identification": { "type": "object", "description": "Payer identification document. Valid types vary by country.", "properties": { "type": { "type": "string", "description": "Identification type (e.g., CPF, CNPJ for Brazil; DNI for Argentina; RFC for Mexico)", "example": "CPF" }, "number": { "type": "string", "description": "Identification number (no formatting — digits only)", "example": "12345678909" } } }, "Phone": { "type": "object", "properties": { "area_code": { "type": "string", "example": "11" }, "number": { "type": "string", "example": "987654321" } } }, "Address": { "type": "object", "properties": { "zip_code": { "type": "string", "example": "01310-100" }, "street_name": { "type": "string", "example": "Av. Paulista" }, "street_number": { "type": "string", "example": "1000" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" } } }, "Payer": { "type": "object", "description": "Payment payer information", "properties": { "id": { "type": "string", "description": "MP payer ID (registered users only)", "example": "123456789" }, "email": { "type": "string", "format": "email", "description": "Payer email address", "example": "test@example.com" }, "identification": { "$ref": "#/components/schemas/Identification" }, "type": { "type": "string", "enum": [ "customer", "registered", "guest" ], "description": "Payer type" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "$ref": "#/components/schemas/Phone" }, "address": { "$ref": "#/components/schemas/Address" } } }, "StoreRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Store display name", "example": "Main Branch — Paulista" }, "external_id": { "type": "string", "description": "Your internal store identifier" }, "business_hours": { "type": "object", "properties": { "monday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:00" }, "close": { "type": "string", "example": "18:00" } } } } } }, "location": { "type": "object", "properties": { "street_number": { "type": "string" }, "street_name": { "type": "string" }, "city_name": { "type": "string" }, "state_name": { "type": "string" }, "zip_code": { "type": "string" }, "latitude": { "type": "number", "format": "float" }, "longitude": { "type": "number", "format": "float" } } } } }, "Store": { "allOf": [ { "$ref": "#/components/schemas/StoreRequest" }, { "type": "object", "properties": { "id": { "type": "string", "description": "Store unique identifier" }, "date_created": { "type": "string", "format": "date-time" }, "date_last_updated": { "type": "string", "format": "date-time" } } } ] }, "POSRequest": { "type": "object", "required": [ "name", "store_id" ], "properties": { "name": { "type": "string", "description": "POS display name", "example": "Caixa 1" }, "store_id": { "type": "string", "description": "Parent store ID" }, "external_id": { "type": "string", "description": "Your internal POS identifier" }, "external_store_id": { "type": "string" }, "category": { "type": "integer", "description": "Business category code" }, "fixed_amount": { "type": "boolean", "description": "When true the POS amount is fixed and cannot be changed by payer", "default": false }, "url": { "type": "string", "format": "uri", "description": "Webhook URL for this specific POS" } } }, "POS": { "allOf": [ { "$ref": "#/components/schemas/POSRequest" }, { "type": "object", "properties": { "id": { "type": "string" }, "qr_code": { "type": "string", "description": "QR code data string for this POS" }, "qr_code_image": { "type": "string", "format": "uri", "description": "URL of QR code image" }, "date_created": { "type": "string", "format": "date-time" }, "date_last_updated": { "type": "string", "format": "date-time" } } } ] }, "Pagination": { "type": "object", "description": "Pagination metadata returned in list/search responses", "properties": { "total": { "type": "integer", "description": "Total number of results", "example": 42 }, "limit": { "type": "integer", "description": "Results per page", "example": 30 }, "offset": { "type": "integer", "description": "Offset of the current page", "example": 0 } } }, "CustomerRequest": { "type": "object", "description": "Request body to create or update a customer", "properties": { "email": { "type": "string", "format": "email", "description": "Customer email address (unique identifier)", "example": "customer@example.com" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "$ref": "#/components/schemas/Phone" }, "identification": { "$ref": "#/components/schemas/Identification" }, "address": { "$ref": "#/components/schemas/Address" }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } }, "Customer": { "type": "object", "description": "A stored MercadoPago customer", "properties": { "id": { "type": "string", "description": "Customer unique identifier", "example": "123456789-abcd" }, "email": { "type": "string", "format": "email" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "$ref": "#/components/schemas/Phone" }, "identification": { "$ref": "#/components/schemas/Identification" }, "address": { "$ref": "#/components/schemas/Address" }, "date_registered": { "type": "string", "format": "date-time" }, "date_created": { "type": "string", "format": "date-time" }, "date_last_updated": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "cards": { "type": "array", "items": { "$ref": "#/components/schemas/Card" }, "description": "Saved cards for this customer" }, "default_card": { "type": "string", "description": "ID of the customer's default card" } } }, "CustomerSearchResult": { "type": "object", "properties": { "paging": { "$ref": "#/components/schemas/Pagination" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } } }, "SaveCardRequest": { "type": "object", "required": [ "token" ], "description": "Request body to save a card to a customer. The card token must be created client-side via MercadoPago.js / MP Secure Fields before calling this endpoint. Raw card data (PAN, CVV) must never be sent to your server.", "properties": { "token": { "type": "string", "description": "Single-use card token from MercadoPago.js", "example": "YOUR_ACCESS_TOKEN" } } }, "Card": { "type": "object", "description": "A tokenized card saved to a customer (never contains full PAN or CVV)", "properties": { "id": { "type": "string", "description": "Card unique identifier", "example": "1234567890" }, "customer_id": { "type": "string" }, "first_six_digits": { "type": "string", "description": "First 6 digits of card (BIN — identifies issuer and type)", "example": "411111" }, "last_four_digits": { "type": "string", "description": "Last 4 digits of card", "example": "4321" }, "expiration_month": { "type": "integer", "minimum": 1, "maximum": 12, "example": 12 }, "expiration_year": { "type": "integer", "example": 2028 }, "date_created": { "type": "string", "format": "date-time" }, "date_last_updated": { "type": "string", "format": "date-time" }, "cardholder": { "type": "object", "properties": { "name": { "type": "string", "description": "Name on card" }, "identification": { "$ref": "#/components/schemas/Identification" } } }, "payment_method": { "type": "object", "properties": { "id": { "type": "string", "example": "visa" }, "name": { "type": "string", "example": "Visa" }, "payment_type_id": { "type": "string", "example": "credit_card" }, "thumbnail": { "type": "string", "format": "uri" } } }, "issuer": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "security_code": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "mandatory", "optional" ] }, "length": { "type": "integer", "example": 3 } } } } }, "CardTokenRequest": { "type": "object", "required": [ "card_number", "expiration_month", "expiration_year", "security_code", "cardholder" ], "description": "Card tokenization request. This is a CLIENT-SIDE ONLY operation — use MercadoPago.js or MP Secure Fields to call this endpoint from the browser. Never send raw card data through your server.", "properties": { "card_number": { "type": "string", "description": "Full card PAN — client-side only, never server-side", "example": "4111111111111111" }, "expiration_month": { "type": "integer", "minimum": 1, "maximum": 12, "example": 12 }, "expiration_year": { "type": "integer", "example": 2028 }, "security_code": { "type": "string", "description": "CVV / CVC — client-side only", "example": "123" }, "cardholder": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name exactly as printed on card", "example": "JOHN DOE" }, "identification": { "$ref": "#/components/schemas/Identification" } } } } }, "CardToken": { "type": "object", "description": "A single-use card token representing a card. Expires in 7 days or after first use. Use this token in payment or order creation requests.", "properties": { "id": { "type": "string", "description": "Token unique identifier — use as the `token` field in payments", "example": "YOUR_ACCESS_TOKEN" }, "first_six_digits": { "type": "string", "example": "411111" }, "last_four_digits": { "type": "string", "example": "4321" }, "expiration_month": { "type": "integer" }, "expiration_year": { "type": "integer" }, "date_created": { "type": "string", "format": "date-time" }, "date_due": { "type": "string", "format": "date-time", "description": "Token expiry (7 days after creation)" }, "luhn_validation": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "used", "expired" ] }, "card_id": { "type": "string", "description": "Linked saved card ID (if token was created from a saved card)" }, "cardholder": { "type": "object", "properties": { "name": { "type": "string" }, "identification": { "$ref": "#/components/schemas/Identification" } } } } }, "PaymentRequest": { "type": "object", "required": [ "transaction_amount", "payer" ], "description": "Request body to create a payment. For card payments, `token` and `payment_method_id` are required. For cash/offline methods, only `payment_method_id` is required.", "properties": { "transaction_amount": { "type": "number", "format": "float", "description": "Payment amount as a decimal number. MercadoPago does NOT use integer cents — send 100.50 for R$100,50 (not 10050). CLP uses 0 decimal places.", "example": 100.5, "minimum": 0.01 }, "token": { "type": "string", "description": "Card token created client-side via MercadoPago.js / MP Secure Fields. Required for credit/debit card payments. Single-use; expires in 7 days.", "example": "YOUR_ACCESS_TOKEN" }, "description": { "type": "string", "description": "Description of the purchased product or service", "example": "Premium subscription — 1 month" }, "installments": { "type": "integer", "description": "Number of installments (1 = no installments)", "example": 1, "minimum": 1 }, "payment_method_id": { "type": "string", "description": "Payment method identifier. Examples: visa, master, bolbradesco (Boleto), pix, oxxo, rapipago, pse. Use GET /v1/payment_methods to list available methods for a given site_id.", "example": "visa" }, "issuer_id": { "type": "string", "description": "Card issuer ID (required for some credit cards)", "example": "310" }, "payer": { "$ref": "#/components/schemas/PaymentPayer" }, "capture": { "type": "boolean", "description": "Two-step payment flow: set false to only authorize (reserve funds), then PUT /v1/payments/{id} with capture=true to capture. Debit cards do not support two-step capture.", "default": true }, "binary_mode": { "type": "boolean", "description": "When true, payments can only be in_process → approved or rejected — no pending state. Useful for in-store flows.", "default": false }, "external_reference": { "type": "string", "description": "Your internal order or reference ID. Max 256 chars.", "example": "ORDER-2024-001234" }, "notification_url": { "type": "string", "format": "uri", "description": "URL to receive IPN notifications when payment status changes. DEPRECATED — use Webhooks instead.", "deprecated": true }, "statement_descriptor": { "type": "string", "description": "Text that appears on the payer's card statement. Max 22 chars.", "example": "MYSTORE.COM", "maxLength": 22 }, "callback_url": { "type": "string", "format": "uri", "description": "Redirect URL after bank transfer (redirect-based methods only)" }, "date_of_expiration": { "type": "string", "format": "date-time", "description": "Expiration date for cash/offline payment methods (boleto, OXXO, etc.). ISO 8601 format. Default varies by method.", "example": "2024-12-31T23:59:59.000-03:00" }, "metadata": { "type": "object", "description": "Free key-value object for your own internal data (not used by MP)", "additionalProperties": true }, "additional_info": { "$ref": "#/components/schemas/PaymentAdditionalInfo" }, "application_fee": { "type": "number", "format": "float", "description": "Marketplace fee charged to the seller (marketplace integrations only)", "example": 1.5 }, "coupon_code": { "type": "string", "description": "Discount coupon code" }, "coupon_amount": { "type": "number", "format": "float", "description": "Coupon discount value" } } }, "PaymentPayer": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "customer@example.com" }, "id": { "type": "string", "description": "MercadoPago user ID (for registered users)" }, "identification": { "$ref": "#/components/schemas/Identification" }, "type": { "type": "string", "enum": [ "customer", "registered", "guest" ] } } }, "PaymentAdditionalInfo": { "type": "object", "description": "Additional context for fraud scoring and installment calculation", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentItem" } }, "payer": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "$ref": "#/components/schemas/Phone" }, "address": { "$ref": "#/components/schemas/Address" }, "registration_date": { "type": "string", "format": "date-time" } } }, "shipments": { "type": "object", "properties": { "receiver_address": { "$ref": "#/components/schemas/Address" } } } } }, "PaymentItem": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category_id": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "number", "format": "float" } } }, "Payment": { "type": "object", "description": "A MercadoPago payment object", "properties": { "id": { "type": "integer", "description": "Payment unique identifier", "example": 1234567890 }, "date_created": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000-03:00" }, "date_approved": { "type": "string", "format": "date-time", "nullable": true }, "date_last_updated": { "type": "string", "format": "date-time" }, "date_of_expiration": { "type": "string", "format": "date-time", "nullable": true }, "money_release_date": { "type": "string", "format": "date-time", "nullable": true }, "operation_type": { "type": "string", "enum": [ "regular_payment", "money_transfer", "recurring_payment", "account_fund", "payment_addition", "cellphone_recharge", "pos_payment", "money_exchange" ] }, "issuer_id": { "type": "string", "nullable": true }, "payment_method_id": { "type": "string", "example": "visa" }, "payment_type_id": { "type": "string", "enum": [ "account_money", "ticket", "bank_transfer", "atm", "credit_card", "debit_card", "prepaid_card", "digital_currency", "digital_wallet", "voucher_card", "crypto", "pix" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "authorized", "in_process", "in_mediation", "rejected", "cancelled", "refunded", "charged_back" ], "description": "Current payment status. Key values: approved — payment completed successfully; pending — awaiting payer action (e.g., Boleto payment); in_process — under review; rejected — payment declined.", "example": "approved" }, "status_detail": { "type": "string", "description": "Detailed reason for the current status", "example": "accredited" }, "currency_id": { "$ref": "#/components/schemas/CurrencyId" }, "description": { "type": "string" }, "payer": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "identification": { "$ref": "#/components/schemas/Identification" }, "type": { "type": "string" } } }, "metadata": { "type": "object", "additionalProperties": true }, "additional_info": { "type": "object" }, "external_reference": { "type": "string" }, "transaction_amount": { "type": "number", "format": "float", "description": "Original payment amount (decimal, not cents)" }, "transaction_amount_refunded": { "type": "number", "format": "float", "description": "Total amount refunded so far" }, "coupon_amount": { "type": "number", "format": "float" }, "transaction_details": { "type": "object", "properties": { "net_received_amount": { "type": "number", "format": "float" }, "total_paid_amount": { "type": "number", "format": "float" }, "overpaid_amount": { "type": "number", "format": "float" }, "external_resource_url": { "type": "string", "format": "uri", "description": "Boleto/OXXO/cash payment URL or barcode" }, "installment_amount": { "type": "number", "format": "float" } } }, "captured": { "type": "boolean" }, "binary_mode": { "type": "boolean" }, "statement_descriptor": { "type": "string" }, "installments": { "type": "integer" }, "card": { "type": "object", "description": "Card data (last 4 digits only — never full PAN)", "properties": { "last_four_digits": { "type": "string", "example": "4321" }, "first_six_digits": { "type": "string", "example": "411111" }, "expiration_year": { "type": "integer" }, "expiration_month": { "type": "integer" }, "date_created": { "type": "string", "format": "date-time" }, "date_last_updated": { "type": "string", "format": "date-time" }, "cardholder": { "type": "object", "properties": { "name": { "type": "string" }, "identification": { "$ref": "#/components/schemas/Identification" } } } } }, "notification_url": { "type": "string", "format": "uri", "deprecated": true }, "processing_mode": { "type": "string", "enum": [ "aggregator", "gateway" ] } } }, "Refund": { "type": "object", "description": "A payment refund (partial or full)", "properties": { "id": { "type": "integer", "example": 987654321 }, "payment_id": { "type": "integer" }, "date_created": { "type": "string", "format": "date-time" }, "amount": { "type": "number", "format": "float", "description": "Refunded amount (decimal)" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "refund_mode": { "type": "string", "enum": [ "standard", "instant" ] }, "status": { "type": "string", "enum": [ "approved", "in_process", "rejected" ] } } }, "RefundRequest": { "type": "object", "description": "Request body for creating a refund. Omit amount for a full refund.", "properties": { "amount": { "type": "number", "format": "float", "description": "Amount to refund. Omit for a full refund.", "example": 50.0 } } }, "PaymentSearchResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "paging": { "$ref": "#/components/schemas/Pagination" } } }, "ReportConfig": { "type": "object", "description": "Configuration for scheduled report generation", "properties": { "columns": { "type": "array", "description": "Columns to include in the report", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "DATE" }, "alias": { "type": "string", "example": "transaction_date" } } } }, "file_name_prefix": { "type": "string", "description": "Prefix for generated report filenames", "example": "releases_report" }, "frequency": { "type": "object", "description": "Schedule frequency for automatic generation", "properties": { "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "type": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] } } }, "sftp_info": { "type": "object", "description": "SFTP destination for automatic delivery (optional)", "properties": { "server": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string" }, "remote_dir": { "type": "string" } } }, "separator": { "type": "string", "description": "CSV column separator character", "enum": [ ",", ";", "" ], "default": "," }, "display_timezone": { "type": "string", "description": "Timezone for date columns (IANA format)", "example": "America/Sao_Paulo" }, "notification_email_list": { "type": "array", "description": "Email addresses to notify when report is ready", "items": { "type": "string", "format": "email" } } } }, "ReportRequest": { "type": "object", "required": [ "begin_date", "end_date" ], "description": "Request body to generate a one-time report", "properties": { "begin_date": { "type": "string", "format": "date-time", "description": "Start of the reporting period (ISO 8601)", "example": "2024-01-01T00:00:00Z" }, "end_date": { "type": "string", "format": "date-time", "description": "End of the reporting period (ISO 8601)", "example": "2024-01-31T23:59:59Z" } } }, "ReportTask": { "type": "object", "description": "Status of a report generation task", "properties": { "id": { "type": "string", "description": "Task unique identifier", "example": "task_abc123" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "done", "failed" ], "description": "pending — queued; in_progress — generating; done — ready to download; failed — generation error" }, "begin_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "download_url": { "type": "string", "format": "uri", "description": "Download URL (present when status=done)", "nullable": true } } }, "ReportEntry": { "type": "object", "description": "A generated report file entry", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "available", "expired" ] }, "date_created": { "type": "string", "format": "date-time" }, "date_last_updated": { "type": "string", "format": "date-time" }, "begin_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "file_name": { "type": "string", "example": "releases_report_2024-01-01_2024-01-31.csv" } } }, "ReportListResult": { "type": "object", "properties": { "paging": { "$ref": "#/components/schemas/Pagination" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ReportEntry" } } } }, "SubscriptionPlanRequest": { "type": "object", "required": [ "reason", "auto_recurring" ], "description": "Request body to create a subscription plan (preapproval_plan). A plan defines the recurring billing terms. Individual subscriptions (preapproval) are then created referencing this plan.", "properties": { "reason": { "type": "string", "description": "Plan description shown to the payer", "example": "Monthly Premium Subscription" }, "auto_recurring": { "$ref": "#/components/schemas/AutoRecurring" }, "payment_methods_allowed": { "type": "object", "properties": { "payment_types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } } } }, "payment_methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } } } } } }, "back_url": { "type": "string", "format": "uri", "description": "Redirect URL after subscription setup" } } }, "AutoRecurring": { "type": "object", "required": [ "frequency", "frequency_type", "transaction_amount", "currency_id" ], "properties": { "frequency": { "type": "integer", "description": "Billing interval (e.g., 1 for monthly, 7 for weekly)", "example": 1 }, "frequency_type": { "type": "string", "enum": [ "months", "days" ], "description": "Unit for the billing interval", "example": "months" }, "transaction_amount": { "type": "number", "format": "float", "description": "Amount to charge each cycle (decimal, not cents)", "example": 29.9 }, "currency_id": { "$ref": "#/components/schemas/CurrencyId" }, "free_trial": { "type": "object", "description": "Optional free trial period before billing starts", "properties": { "frequency": { "type": "integer", "example": 14 }, "frequency_type": { "type": "string", "enum": [ "months", "days" ], "example": "days" } } }, "repetitions": { "type": "integer", "description": "Total number of billing cycles (null = indefinite)", "nullable": true } } }, "SubscriptionPlan": { "type": "object", "description": "A subscription plan (preapproval_plan)", "properties": { "id": { "type": "string", "example": "2c9380847e9c5058017ea64ea8260b60" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "auto_recurring": { "$ref": "#/components/schemas/AutoRecurring" }, "date_created": { "type": "string", "format": "date-time" }, "last_modified": { "type": "string", "format": "date-time" }, "init_point": { "type": "string", "format": "uri", "description": "URL to subscribe users to this plan" } } }, "SubscriptionRequest": { "type": "object", "required": [ "reason", "payer_email", "auto_recurring" ], "description": "Request body to create a subscription (preapproval). Either reference a preapproval_plan or define auto_recurring inline.", "properties": { "preapproval_plan_id": { "type": "string", "description": "Reference a previously created plan (recommended)" }, "reason": { "type": "string", "description": "Subscription description shown to payer", "example": "Monthly Premium — Acme Inc." }, "payer_email": { "type": "string", "format": "email", "description": "Payer's email address" }, "card_token_id": { "type": "string", "description": "Card token for credit card subscriptions" }, "auto_recurring": { "$ref": "#/components/schemas/AutoRecurring" }, "back_url": { "type": "string", "format": "uri" }, "external_reference": { "type": "string", "example": "CUSTOMER-ID-12345" }, "status": { "type": "string", "enum": [ "pending", "authorized", "paused", "cancelled" ], "description": "Initial status (default is pending until payer authorizes)" } } }, "Subscription": { "type": "object", "description": "A MercadoPago subscription (preapproval)", "properties": { "id": { "type": "string", "example": "2c9380847e9c5058017ea64ea8260b60" }, "payer_id": { "type": "integer" }, "payer_email": { "type": "string", "format": "email" }, "preapproval_plan_id": { "type": "string" }, "reason": { "type": "string" }, "external_reference": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "authorized", "paused", "cancelled" ] }, "date_created": { "type": "string", "format": "date-time" }, "last_modified": { "type": "string", "format": "date-time" }, "auto_recurring": { "$ref": "#/components/schemas/AutoRecurring" }, "summarized": { "type": "object", "description": "Subscription billing summary", "properties": { "quotas": { "type": "integer" }, "charged_quantity": { "type": "integer" }, "pending_charge_quantity": { "type": "integer" }, "charged_amount": { "type": "number", "format": "float" }, "pending_charge_amount": { "type": "number", "format": "float" } } }, "next_payment_date": { "type": "string", "format": "date-time" }, "payment_method_id": { "type": "string" }, "card_id": { "type": "integer" }, "init_point": { "type": "string", "format": "uri", "description": "Authorization URL — send payer here to confirm subscription" } } }, "AuthorizedPayment": { "type": "object", "description": "An invoice generated by a subscription billing cycle", "properties": { "id": { "type": "integer" }, "preapproval_id": { "type": "string" }, "status": { "type": "string", "enum": [ "scheduled", "processed", "recycling", "cancelled" ] }, "status_detail": { "type": "string" }, "date_created": { "type": "string", "format": "date-time" }, "last_modified": { "type": "string", "format": "date-time" }, "transaction_amount": { "type": "number", "format": "float" }, "currency_id": { "$ref": "#/components/schemas/CurrencyId" }, "payment": { "type": "object", "properties": { "id": { "type": "integer", "description": "Linked payment ID in /v1/payments" }, "status": { "type": "string" }, "status_detail": { "type": "string" } } } } }, "SubscriptionSearchResult": { "type": "object", "properties": { "paging": { "$ref": "#/components/schemas/Pagination" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } } } }, "WebhookNotification": { "type": "object", "description": "Webhook notification payload sent to your notification URL when a resource changes. Validate the x-signature HMAC-SHA256 header before processing. After receiving, GET the resource URL to fetch the full updated object.", "required": [ "id", "type", "data" ], "properties": { "id": { "type": "integer", "description": "Notification unique ID (use for deduplication)", "example": 12345678 }, "type": { "type": "string", "description": "Resource type that triggered the notification", "enum": [ "payment", "merchant_order", "subscription_preapproval", "subscription_preapproval_plan", "subscription_authorized_payment", "point_integration_wh", "chargebacks", "delivery" ], "example": "payment" }, "date_created": { "type": "string", "format": "date-time" }, "user_id": { "type": "integer", "description": "MP user ID that owns the resource" }, "api_version": { "type": "string", "example": "v1" }, "action": { "type": "string", "enum": [ "payment.created", "payment.updated", "subscription.authorized", "subscription.cancelled", "order.created", "order.updated", "point_integration_wh" ], "example": "payment.updated" }, "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Resource ID. Fetch this via GET at the resource URL to get full details. Do not rely on the webhook payload alone — always GET the resource.", "example": "1234567890" } } } } }, "WebhookSignatureHeader": { "type": "object", "description": "The x-signature header value format: ts=,v1=. Validate using HMAC-SHA256 with your webhook secret key. See: https://www.mercadopago.com/developers/en/docs/your-integrations/notifications/webhooks", "properties": { "ts": { "type": "string", "description": "Unix timestamp of the notification" }, "v1": { "type": "string", "description": "HMAC-SHA256 signature of \"id:[notif_id];request-id:[req_id];ts:[ts];\"" } } }, "MerchantOrder": { "type": "object", "description": "A merchant order groups multiple payments for a single purchase. Updated when any associated payment changes status.", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "opened", "closed", "expired" ] }, "external_reference": { "type": "string" }, "preference_id": { "type": "string" }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "transaction_amount": { "type": "number", "format": "float" }, "total_paid_amount": { "type": "number", "format": "float" }, "shipping_cost": { "type": "number", "format": "float" }, "currency_id": { "$ref": "#/components/schemas/CurrencyId" }, "status": { "type": "string" }, "status_detail": { "type": "string" }, "operation_type": { "type": "string" }, "date_created": { "type": "string", "format": "date-time" }, "date_approved": { "type": "string", "format": "date-time" } } } }, "items": { "type": "array", "items": { "type": "object" } }, "date_created": { "type": "string", "format": "date-time" }, "last_updated": { "type": "string", "format": "date-time" }, "total_amount": { "type": "number", "format": "float" }, "paid_amount": { "type": "number", "format": "float" }, "refunded_amount": { "type": "number", "format": "float" }, "shipping": { "type": "object" }, "notification_url": { "type": "string", "format": "uri", "deprecated": true } } }, "OrderRequest": { "type": "object", "required": [ "type", "total_amount", "transactions", "payer" ], "description": "Request body to create an Order. Supports automatic (single-stage) and manual (multi-stage) processing modes. Use processing_mode=automatic for most integrations.\n", "properties": { "type": { "type": "string", "enum": [ "online" ], "description": "Order type. Only \"online\" is supported for online payments.", "example": "online" }, "processing_mode": { "type": "string", "enum": [ "automatic", "manual" ], "description": "automatic — MP processes all transactions immediately in a single stage. manual — transactions are processed in configurable stages; use the /process endpoint to trigger processing after creation.\n", "example": "automatic" }, "capture_mode": { "type": "string", "enum": [ "automatic", "manual", "automatic_async" ], "description": "automatic — authorize and capture funds at the same time. manual — authorize only (reserve funds); capture later with /capture endpoint. automatic_async — order may remain in status=processing while awaiting async update; final status delivered via webhook.\n", "example": "automatic" }, "total_amount": { "type": "string", "description": "Total amount to be paid as a decimal string. Must equal the sum of all payment transaction amounts. Example: \"100.00\".\n", "example": "100.00" }, "external_reference": { "type": "string", "description": "Your internal order reference ID. Returned in all order responses.", "example": "ORDER-2024-001234" }, "description": { "type": "string", "description": "Description of the purchased product or service.", "example": "Premium subscription" }, "payer": { "$ref": "#/components/schemas/OrderPayer" }, "transactions": { "$ref": "#/components/schemas/OrderTransactions" }, "config": { "$ref": "#/components/schemas/OrderConfig" }, "items": { "type": "array", "description": "Items included in the order.", "items": { "$ref": "#/components/schemas/OrderItem" } }, "shipment": { "$ref": "#/components/schemas/OrderShipment" }, "additional_info": { "type": "object", "description": "Additional information required for specific payment methods (e.g. PSE).", "properties": { "payer": { "type": "object", "properties": { "ip_address": { "type": "string", "description": "IP address of the payer. Required for PSE payments.", "example": "200.100.50.25" } } } } }, "integration_data": { "type": "object", "description": "Integration metadata used by MercadoPago internally.", "properties": { "platform_id": { "type": "string" }, "sponsor_id": { "type": "integer" } } } } }, "OrderTransactions": { "type": "object", "description": "Payment transactions for this order. Currently supports one transaction.", "properties": { "payments": { "type": "array", "description": "Payment transaction(s). Required when processing_mode=automatic. Must not be present when processing_mode=manual (add via POST /orders/{id}/transactions).\n", "items": { "$ref": "#/components/schemas/OrderPayment" } } } }, "OrderPayment": { "type": "object", "required": [ "amount", "payment_method" ], "properties": { "amount": { "type": "string", "description": "Transaction amount as a decimal string.", "example": "100.00" }, "payment_method": { "$ref": "#/components/schemas/OrderPaymentMethod" }, "expiration_time": { "type": "string", "description": "Transaction expiration in ISO 8601 duration format (e.g. \"P1D\" = 1 day, \"PT20M\" = 20 minutes). Applies to ticket and bank transfer payment methods.\n", "example": "P1D" }, "date_of_expiration": { "type": "string", "format": "date-time", "description": "Absolute expiration date-time. Takes precedence over expiration_time if both provided." } } }, "OrderPaymentMethod": { "type": "object", "required": [ "id", "type" ], "description": "Payment method for the transaction. Use GET /v1/payment_methods to list available methods for your site.\n", "properties": { "id": { "type": "string", "description": "Payment method identifier. Examples by type: Cards: visa, master, elo, hipercard, amex. Ticket/cash: bolbradesco (Boleto), oxxo, rapipago, pagofacil. Bank transfer: pix, clabe (SPEI), pse.\n", "example": "visa" }, "type": { "type": "string", "enum": [ "credit_card", "debit_card", "bank_transfer", "ticket", "digital_wallet", "account_money" ], "example": "credit_card" }, "token": { "type": "string", "description": "Card token. Required for credit_card and debit_card types.", "example": "1c87b6b301010101ddcd92f9bbbb3be2" }, "installments": { "type": "integer", "description": "Number of installments. Use 1 for no installments.", "minimum": 1, "example": 1 }, "statement_descriptor": { "type": "string", "description": "Text shown on payer's card statement. Maximum 50 characters.", "maxLength": 50 }, "financial_institution": { "type": "string", "description": "Bank code. Required for PSE (Colombia) bank transfer payments.", "example": "1051" } } }, "OrderPayer": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "customer@example.com" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "identification": { "type": "object", "properties": { "type": { "type": "string", "description": "Document type (e.g. CPF, CNPJ, DNI, NIT, RFC)", "example": "CPF" }, "number": { "type": "string", "description": "Document number (digits only, no formatting)", "example": "99999999999" } } }, "phone": { "type": "object", "properties": { "area_code": { "type": "string", "example": "11" }, "number": { "type": "string", "example": "43434343" } } }, "address": { "type": "object", "properties": { "zip_code": { "type": "string" }, "street_name": { "type": "string" }, "street_number": { "type": "string" }, "neighborhood": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "complement": { "type": "string" } } }, "entity_type": { "type": "string", "enum": [ "individual", "association" ], "description": "Payer entity type. Required for PSE (Colombia) payments." } } }, "OrderConfig": { "type": "object", "description": "Optional settings for the order.", "properties": { "online": { "type": "object", "description": "Settings for online card transactions.", "properties": { "transaction_security": { "type": "object", "description": "3DS (3D Secure) configuration. After creating the order, the response indicates if a challenge is required via transactions.payments[].payment_method.transaction_security.\n", "properties": { "validation": { "type": "string", "enum": [ "supported", "required", "never" ], "description": "supported — run 3DS when supported by issuer; required — always run 3DS, reject if not supported; never — skip 3DS entirely.\n" }, "liability_shift": { "type": "string", "enum": [ "required", "not_required" ], "description": "Required when validation is not \"never\". required — only approve if liability shifts to issuer; not_required — approve regardless of liability shift outcome.\n" } } }, "callback_url": { "type": "string", "format": "uri", "description": "Redirect URL after PSE bank authentication completes.", "example": "https://merchant.com/pse/return" } } } } }, "OrderItem": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "unit_price": { "type": "number", "format": "float" }, "category_id": { "type": "string" } } }, "OrderShipment": { "type": "object", "properties": { "address": { "type": "object", "properties": { "zip_code": { "type": "string" }, "street_name": { "type": "string" }, "street_number": { "type": "string" }, "neighborhood": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "complement": { "type": "string" } } } } }, "Order": { "type": "object", "description": "A MercadoPago Order.", "properties": { "id": { "type": "string", "description": "Order unique identifier, automatically generated by MercadoPago.", "example": "01JG28GRB9NYTG6VVS3R5N58YT" }, "type": { "type": "string", "example": "online" }, "processing_mode": { "type": "string", "enum": [ "automatic", "manual" ] }, "capture_mode": { "type": "string", "enum": [ "automatic", "manual", "automatic_async" ] }, "status": { "type": "string", "enum": [ "created", "processed", "action_required", "processing", "canceled" ], "description": "created — order created, waiting for processing. processed — all transactions successfully processed. action_required — integrator action needed (e.g. capture an authorized payment). processing — being processed; no action needed from integrator. canceled — order canceled, will not be processed further.\n", "example": "processed" }, "status_detail": { "type": "string", "enum": [ "created", "accredited", "in_process", "in_review", "waiting_payment", "waiting_capture", "waiting_transfer" ], "description": "accredited — payment credited; waiting_payment — waiting for payer to complete offline payment; waiting_capture — authorized payment awaiting capture; waiting_transfer — waiting for bank transfer.\n", "example": "accredited" }, "external_reference": { "type": "string" }, "total_amount": { "type": "string", "description": "Total order amount as decimal string.", "example": "100.00" }, "total_paid_amount": { "type": "string", "description": "Total amount effectively paid so far.", "example": "100.00" }, "description": { "type": "string" }, "country_code": { "type": "string", "description": "site_id of the order (e.g. MLB, MLA).", "example": "MLB" }, "user_id": { "type": "integer", "description": "Collector (seller) user ID." }, "created_date": { "type": "string", "format": "date-time" }, "last_updated_date": { "type": "string", "format": "date-time" }, "client_token": { "type": "string", "description": "Token for client-side rendering of the payment UI (e.g. Bricks). Only returned when applicable.\n" }, "payer": { "$ref": "#/components/schemas/OrderPayer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "shipment": { "$ref": "#/components/schemas/OrderShipment" }, "transactions": { "type": "object", "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/OrderTransactionPayment" } } } }, "config": { "$ref": "#/components/schemas/OrderConfig" }, "integration_data": { "type": "object" } } }, "OrderTransactionPayment": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction ID, automatically generated by MercadoPago." }, "amount": { "type": "string", "description": "Transaction amount.", "example": "100.00" }, "paid_amount": { "type": "string", "description": "Amount effectively paid." }, "reference_id": { "type": "string", "description": "External reference for this transaction." }, "status": { "type": "string", "enum": [ "created", "processed", "action_required", "processing" ], "description": "created — transaction created; processed — transaction successfully processed; action_required — integrator must act (e.g. capture); processing — awaiting asynchronous result.\n" }, "status_detail": { "type": "string", "enum": [ "accredited", "waiting_capture", "created", "pending_review_manual", "in_process" ] }, "date_of_expiration": { "type": "string", "format": "date-time" }, "expiration_time": { "type": "string", "description": "Expiration duration in ISO 8601 format." }, "payment_method": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "token": { "type": "string" }, "installments": { "type": "integer" }, "statement_descriptor": { "type": "string" }, "ticket_url": { "type": "string", "format": "uri", "description": "URL to view or print the ticket (Boleto, OXXO, etc.)." }, "barcode_content": { "type": "string", "description": "Barcode string for offline payment methods." }, "reference": { "type": "string", "description": "Reference number for offline payment methods." }, "verification_code": { "type": "string" }, "financial_institution": { "type": "string" }, "redirect_url": { "type": "string", "format": "uri", "description": "Redirect URL for PSE bank transfer (Colombia). In production, redirect the payer to this URL to complete authentication at their bank.\n" }, "digitable_line": { "type": "string", "description": "Digitable line for Boleto payments." }, "qr_code": { "type": "string", "description": "QR code string for Pix payments." }, "qr_code_base64": { "type": "string", "description": "QR code image as Base64 for Pix payments." }, "e2e_id": { "type": "string", "description": "End-to-end identifier for Pix transactions (mandatory tracking code)." }, "transaction_security": { "type": "object", "description": "3DS challenge result.", "properties": { "status": { "type": "string", "enum": [ "pending", "success", "failed" ] }, "redirect_url": { "type": "string", "format": "uri", "description": "URL to redirect payer to complete 3DS challenge (when status=pending)." } } } } } } }, "OrderRefundRequest": { "type": "object", "description": "Refund request for an order. Omit transactions for a full refund. Include specific transaction amounts for partial refunds.\n", "properties": { "transactions": { "type": "array", "description": "Transactions to refund. Omit for full order refund.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction ID to refund." }, "amount": { "type": "string", "description": "Amount to refund. Omit for full transaction refund." } } } } } }, "OrderSearchResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "paging": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } }, "UpdateCardRequest": { "type": "object", "description": "Request body to update a saved card's expiry or cardholder data.", "properties": { "expiration_month": { "type": "integer", "minimum": 1, "maximum": 12 }, "expiration_year": { "type": "integer" }, "cardholder": { "type": "object", "properties": { "name": { "type": "string", "description": "Name as it appears on the card." }, "identification": { "$ref": "#/components/schemas/Identification" } } } } }, "PaymentUpdateRequest": { "type": "object", "description": "Request body to update a payment (capture, cancel, or extend expiration).", "properties": { "capture": { "type": "boolean", "description": "Set true to capture an authorized payment." }, "status": { "type": "string", "enum": [ "cancelled" ], "description": "Set to cancelled to cancel an authorized payment." }, "transaction_amount": { "type": "number", "format": "float", "description": "Partial capture amount (must be ≤ original authorized amount)." }, "date_of_expiration": { "type": "string", "format": "date-time", "description": "New expiration date for cash payment methods." } } }, "SubscriptionUpdateRequest": { "type": "object", "description": "Request body to update a subscription.", "properties": { "reason": { "type": "string" }, "external_reference": { "type": "string" }, "back_url": { "type": "string", "format": "uri" }, "auto_recurring": { "$ref": "#/components/schemas/AutoRecurring" }, "card_token_id": { "type": "string", "description": "New card token to update the payment method." }, "card_token_id_secondary": { "type": "string", "description": "Token for secondary/fallback payment method card." }, "payment_method_id_secondary": { "type": "string", "description": "Secondary payment method identifier for fallback charges." }, "status": { "type": "string", "enum": [ "pending", "authorized", "paused", "cancelled" ] } } }, "AuthorizedPaymentSearchResult": { "type": "object", "properties": { "paging": { "$ref": "#/components/schemas/Pagination" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AuthorizedPayment" } } } } } } }