API Reference - Mercado Pago Developers

Recursos para IA

Crear order

Este endpoint permite crear una order en modo manual para flujos de pago con Checkout Pro. En caso de éxito, la solicitud devolverá una respuesta con el estado 201 y un checkout_url para redirigir al comprador.

POST

https://api.mercadopago.com/v1/orders

Header

ObligatorioOpcional

Body

ObligatorioOpcional

empty_required_header

El header X-Idempotency-Key es requerido y no fue enviado. Vuelve a realizar la solicitud incluyéndolo.

invalid_idempotency_key_length

El valor enviado en el header X-Idempotency-Key excedió el tamaño máximo permitido. El header acepta valores entre 1 y 128 caracteres.

required_properties

Ciertas propiedades requeridas están ausentes. Chequea el mensaje devuelto en los detalles del error para saber cuál fue el problema y vuelve a intentarlo.

order_items_total_amount_mismatch

El valor ingresado en total_amount no es equivalente a la suma de items[].unit_price multiplicado por items[].quantity de todos los ítems. Por favor, verifica que los valores sean correctos.

invalid_total_amount

El monto total de la order no puede ser cero. Envía un total_amount mayor que cero.

unsupported_properties

Se envió una propiedad que no es soportada. Chequea el mensaje devuelto en los detalles del error para saber cuál fue el problema y vuelve a intentarlo.

property_value

Se envió un valor inválido para alguna propiedad. Chequea el mensaje devuelto en los detalles del error para saber cuál fue el problema y vuelve a intentarlo.

property_type

Se envió un tipo de propiedad incorrecto. Por ejemplo, un valor integer para una propiedad string. Chequea el mensaje devuelto en los detalles del error para saber cuál fue el problema y vuelve a intentarlo.

json_syntax_error

Se envió un JSON inválido. Chequea el mensaje devuelto en los detalles del error para saber cuál fue el problema y vuelve a intentarlo.

minimum_properties

No se envió el número mínimo de propiedades necesarias para ejecutar la solicitud. Chequea el mensaje devuelto en los detalles del error para saber cuál fue el problema y vuelve a intentarlo.

idempotency_validation_failed

Falla en la validación de idempotencia. Intenta enviar la solicitud nuevamente.

401

El valor enviado como Access Token es incorrecto. Por favor, verifícalo y vuelve a intentar realizar la solicitud enviando el valor correcto.

invalid_credentials

No hay soporte para credenciales de prueba. Utiliza usuarios de prueba con credenciales de producción para el entorno de prueba (sandbox) y sus credenciales de producción para el entorno de producción.

forbidden

La aplicación no tiene permisos para acceder a este recurso. Verifica que el Access Token utilizado tenga los permisos y scopes necesarios para esta operación.

PA_UNAUTHORIZED_RESULT_FROM_POLICIES

La cuenta está bloqueada y sus claves de API fueron revocadas. Al menos una política evaluada por el Policy Agent retornó un resultado no autorizado.

idempotency_key_already_used

El valor enviado como header de idempotencia (X-Idempotency-Key) ya fue utilizado. Por favor, vuelve a intentar realizar la solicitud enviando un nuevo valor.

unprocessable_entity

La solicitud no pudo procesarse. Falta identificación del usuario o el payload no cumple las condiciones requeridas.

resource_locked

Clave de idempotencia bloqueada. Por favor, vuelve a intentar después de un tiempo.

too_many_requests

Client ID bloqueado por el gateway porque se alcanzó el límite de solicitudes para el ID en cuestión. Lee el header Retry-After de la respuesta y espera la cantidad de segundos indicada antes de volver a intentarlo. Para mayor resiliencia, implementa backoff exponencial con jitter, es decir, aumenta el tiempo de espera en cada nuevo intento y añade una variación aleatoria para evitar el reenvío simultáneo de muchas solicitudes.

usage_quota_exceeded

Cuota impuesta por el backend de la API porque se alcanzó el límite de solicitudes por cliente. Lee el header Retry-After de la respuesta y espera la cantidad de segundos indicada antes de volver a intentarlo. Para mayor resiliencia, implementa backoff exponencial con jitter, es decir, aumenta el tiempo de espera en cada nuevo intento y añade una variación aleatoria para evitar el reenvío simultáneo de muchas solicitudes.

internal_error

Error genérico. Intenta enviar la solicitud nuevamente.

curl -X POST \
    'https://api.mercadopago.com/v1/orders'\
    -H 'Content-Type: application/json' \
       -H 'Authorization: Bearer ' \
       -H 'X-Idempotency-Key: bdc0a3b6-8a89-45ff-bd5e-6a650551c6b4' \
    -d '{
  "type": "online",
  "total_amount": "50.00",
  "external_reference": "ext_ref_1234",
  "processing_mode": "manual",
  "capture_mode": "automatic_async",
  "marketplace_fee": "11.20",
  "expiration_time": "P1D",
  "payer": {
    "email": "test_payer@example.com",
    "first_name": "María",
    "last_name": "González",
    "phone": {
      "area_code": "11",
      "number": "999998888"
    },
    "identification": {
      "type": "DNI",
      "number": "12345678"
    },
    "address": {
      "zip_code": "C1264AAK",
      "street_name": "Av. Corrientes",
      "street_number": "3039",
      "neighborhood": "Parque Patricios",
      "city": "Buenos Aires"
    }
  },
  "config": {
    "statement_descriptor": "MYSTORE",
    "default_payment_due_date": "P1D",
    "online": {
      "available_from": "2026-01-01T00:00:00Z",
      "allowed_user_type": "account_only",
      "success_url": "https://www.example.com/success",
      "failure_url": "https://www.example.com/failure",
      "pending_url": "https://www.example.com/pending",
      "auto_return": "approved",
      "tracks": [
        {
          "type": "google_ad",
          "values": {
            "conversion_id": "21312312312123",
            "conversion_label": "TEST",
            "pixel_id": "21312312312123"
          }
        }
      ]
    },
    "payment_method": {
      "max_installments": 12,
      "not_allowed_ids": [
        "amex"
      ],
      "not_allowed_types": [
        "credit_card"
      ],
      "installments": {
        "interest_free": {
          "type": "range",
          "values": [
            2,
            6
          ]
        }
      }
    }
  },
  "items": [
    {
      "external_code": "ITEM-001",
      "title": "Product 001",
      "description": "Product description",
      "category_id": "travels",
      "picture_url": "https://example.com/img.jpg",
      "quantity": 1,
      "unit_price": "1000.00",
      "type": "travel",
      "warranty": false,
      "event_date": "2014-06-28T16:53:03.176-04:00"
    }
  ],
  "additional_info": {
    "payer.registration_date": "2020-01-15T00:00:00.000-03:00",
    "payer.authentication_type": "MOBILE",
    "payer.is_prime_user": false,
    "payer.is_first_purchase_online": false,
    "payer.last_purchase": "2025-12-01T00:00:00.000-03:00",
    "travel.passengers": [
      {
        "first_name": "John",
        "last_name": "Smith",
        "identification_type": "DNI",
        "identification_number": "12345678909",
        "item_references": [
          "ITEM-001"
        ]
      }
    ],
    "travel.routes": [
      {
        "departure": "SAO",
        "destination": "RIO",
        "departure_date_time": "2026-03-10T08:00:00.000-03:00",
        "arrival_date_time": "2026-03-10T09:00:00.000-03:00",
        "company": "TAM",
        "item_references": [
          "ITEM-001"
        ]
      }
    ]
  },
  "description": "Smartphone"
}'

{
  "id": "ORDTST01KS5AJ6HTK2HRQ3XJ3C2JCKP9",
  "type": "online",
  "processing_mode": "manual",
  "status": "created",
  "status_detail": "accredited",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "total_paid_amount": "50.00",
  "marketplace_fee": "11.20",
  "checkout_url": "https://www.mercadopago./checkout/v1/redirect?order_id=ORDTST01KS5AJ6HTK2HRQ3XJ3C2JCKP9",
  "expiration_time": "P1D",
  "country_code": "ARG",
  "user_id": "12345",
  "currency": "ARS",
  "capture_mode": "automatic_async",
  "client_token": "eyJhbGciOiJSUzI1NiIs...",
  "created_date": "2024-08-26T13:06:51.045317772Z",
  "last_updated_date": "2024-08-26T13:06:51.045317772Z",
  "integration_data": {
    "application_id": "8772548647196351",
    "integrator_id": "dev_123",
    "platform_id": "1234567890",
    "sponsor": {
      "id": "446566691"
    }
  },
  "config": {
    "online": {
      "callback_url": "https://www.example.com/",
      "success_url": "https://www.example.com/success",
      "failure_url": "https://www.example.com/failure",
      "pending_url": "https://www.example.com/pending",
      "available_from": "2026-05-16T18:32:00Z",
      "auto_return": "approved",
      "retries": {
        "allowed": false
      }
    },
    "payment_method": {
      "max_installments": 12,
      "not_allowed_ids": [
        "amex"
      ],
      "not_allowed_types": [
        "credit_card"
      ],
      "default_type": "credit_card",
      "installments_cost": "seller",
      "installments": {
        "interest_free": {
          "type": "range",
          "values": [
            2,
            6
          ]
        },
        "available": {
          "type": "all"
        }
      }
    }
  },
  "items": [
    {
      "external_code": "ITEM-001",
      "title": "Product 001",
      "description": "Product description",
      "category_id": "travels",
      "picture_url": "https://example.com/img.jpg",
      "quantity": 1,
      "unit_price": "1000.00",
      "type": "travel",
      "warranty": true,
      "event_date": "2014-06-28T16:53:03.176-04:00"
    }
  ],
  "description": "Travel package SAO-RIO with insurance"
}

Documentación

¿Comenzando ahora?

Recursos

Soporte

Partners

Comunidad

Navegación

Recursos y Comunidad

Mercado Pago

País e idioma