PagoEfectivo ATM

Para recibir pagos con PagoEfectivo ATM, es necesario agregar al frontend un formulario que capture los datos del pagador de forma segura.

Si ya tienes un formulario de pago, asegúrate de incluir PagoEfectivo ATM entre las opciones disponibles como se indica a continuación y continúa con el paso Enviar pago.

html
<form id="form-checkout" action="/process_payment" method="post">
  <div>
    <label for="payerFirstName">Nombre</label>
    <input id="form-checkout__payerFirstName" name="payerFirstName" type="text">
  </div>
  <div>
    <label for="payerLastName">Apellido</label>
    <input id="form-checkout__payerLastName" name="payerLastName" type="text">
  </div>
  <div>
    <label for="email">E-mail</label>
    <input id="form-checkout__email" name="email" type="text">
  </div>
  <div>
    <label for="identificationType">Tipo de documento</label>
    <select id="form-checkout__identificationType" name="identificationType"></select>
  </div>
  <div>
    <label for="identificationNumber">Número del documento</label>
    <input id="form-checkout__identificationNumber" name="identificationNumber" type="text">
  </div>
  <div>
    <input type="hidden" name="transactionAmount" id="transactionAmount" value="200">
    <button type="submit">Pagar</button>
  </div>
</form>

Los datos de nombre, apellido e identificación son opcionales para PagoEfectivo ATM. Si optas por recopilar la identificación, obtén los tipos de documento dinámicamente con MercadoPago.js ya configurado en el entorno de desarrollo.

javascript
(async function getIdentificationTypes() {
  try {
    const identificationTypes = await mp.getIdentificationTypes();
    const identificationTypeElement = document.getElementById("form-checkout__identificationType");

    createSelectOptions(identificationTypeElement, identificationTypes);
  } catch (error) {
    return console.error("Error getting identificationTypes: ", error);
  }
})();

function createSelectOptions(element, options, labelsAndKeys = { label: "name", value: "id" }) {
  const { label, value } = labelsAndKeys;
  element.options.length = 0;
  const fragment = document.createDocumentFragment();

  options.forEach((option) => {
    const item = document.createElement("option");
    item.value = option[value];
    item.textContent = option[label];
    fragment.appendChild(item);
  });

  element.appendChild(fragment);
}

El envío del pago se realiza creando una order que contenga la transacción de pago asociada.

Para eso, envía una solicitud con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, utilizada en el backend. Accede a ella en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y los parámetros indicados a continuación al endpoint /v1/ordersPOST y ejecuta la solicitud.

curl
curl --location --request POST 'https://api.mercadopago.com/v1/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
--data-raw '{
  "type": "online",
  "external_reference": "ext_ref_1234",
  "processing_mode": "automatic",
  "total_amount": "200.00",
  "description": "Compra de producto MPE",
  "payer": {
    "email": "test_payer@example.com",
    "first_name": "Juan",
    "last_name": "Pérez",
    "identification": {
      "type": "DNI",
      "number": "12345678"
    }
  },
  "config": {
    "location": {
      "state_id": "PE-LIM"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": "200.00",
        "expiration_time": "P1D",
        "payment_method": {
          "id": "pagoefectivo_atm",
          "type": "atm"
        }
      }
    ]
  }
}'

La creación del pago ocurre de forma asíncrona en la order. Mientras se procesa, la order se devuelve con el estado processing y sin información.

Una vez finalizado el procesamiento, y al tratarse de un medio de pago offline, la order pasa al estado action_required con el detalle waiting_payment, indicando que el comprador aún debe completar el pago en el terminal ATM, tal como se muestra en el siguiente ejemplo de respuesta. Te recomendamos configurar las notificaciones del tópico Order para recibir actualizaciones sobre el cambio de estado, incluyendo los datos actualizados de la order. Alternativamente, puedes optar por enviar una solicitud al endpoint /v1/orders/{id}GET para consultar el estado actualizado.

json
{
  "id": "ORDPE01EXAMPLEPE1234NCAKKBF68N64S",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "description": "Compra de producto MPE",
  "total_amount": "200.00",
  "total_paid_amount": "0.00",
  "country_code": "PER",
  "user_id": "1234567890",
  "status": "action_required",
  "status_detail": "waiting_payment",
  "capture_mode": "automatic_async",
  "currency": "PEN",
  "created_date": "2026-07-29T21:03:42.252Z",
  "last_updated_date": "2026-07-29T21:03:43.985Z",
  "integration_data": {
    "application_id": "1234567890123456"
  },
  "transactions": {
    "payments": [
      {
        "id": "PAYPE01EXAMPLEPE1234BSAR5ZWXX5YZG",
        "amount": "200.00",
        "expiration_time": "P1D",
        "date_of_expiration": "2026-07-30T03:59:59.999+00:00",
        "reference_id": "1234567890",
        "status": "action_required",
        "status_detail": "waiting_payment",
        "payment_method": {
          "id": "pagoefectivo_atm",
          "type": "atm",
          "ticket_url": "https://www.mercadopago.com.pe/payments/1234567890/ticket?caller_id=1234567890&payment_method_id=pagoefectivo_atm&payment_id=1234567890&payment_method_reference_id=1234567890&hash=00000000-0000-0000-0000-000000000000",
          "reference": "1234567890",
          "verification_code": "1234567890",
          "financial_institution": "PagoEfectivo"
        }
      }
    ]
  }
}

Tras crear la order, muestra al comprador la información necesaria para completar el pago en un terminal ATM de la red PagoEfectivo. Estos datos están disponibles en los campos payment_method de la respuesta.

El comprador debe utilizar el verification_code y el reference en el terminal ATM para completar el pago dentro del plazo de vencimiento definido en date_of_expiration.

Una vez que el comprador realice el pago, la order pasa a status: processed. Si configuraste tus notificaciones, esto te será notificado vía webhook.

Si lo deseas, puedes cancelar un pago creado, siempre y cuando se encuentre pendiente o en proceso; es decir, con status=action_required.

Adicionalmente, recomendamos cancelar los pagos que no fueron realizados dentro de la fecha de vencimiento establecida, para evitar problemas de facturación y conciliación.

Para obtener más información, consulta la sección Reembolsos y cancelaciones.