PagoEfectivo ATM

Para receber pagamentos com PagoEfectivo ATM, é necessário adicionar ao frontend um formulário que capture os dados do pagador de forma segura.

Se você já tem um formulário de pagamento, certifique-se de incluir PagoEfectivo ATM entre as opções disponíveis conforme indicado abaixo e continue para a etapa de Enviar pagamento.

html
<form id="form-checkout" action="/process_payment" method="post">
  <div>
    <label for="payerFirstName">Nome</label>
    <input id="form-checkout__payerFirstName" name="payerFirstName" type="text">
  </div>
  <div>
    <label for="payerLastName">Sobrenome</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 do 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>

Os dados de nome, sobrenome e identificação são opcionais para PagoEfectivo ATM. Caso opte por coletar a identificação, obtenha os tipos de documento dinamicamente com o MercadoPago.js já configurado no ambiente de desenvolvimento.

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);
}

O envio do pagamento é realizado criando uma order com a transação de pagamento associada.

Para isso, envie uma requisição com o seu Access Token de testeChave privada da aplicação criada no Mercado Pago, utilizada no backend. Acesse-a em Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e os parâmetros indicados abaixo para o endpoint /v1/ordersPOST e execute a requisição.

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 produto MPE",
  "payer": {
    "email": "test_payer@example.com",
    "first_name": "João",
    "last_name": "Silva",
    "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"
        }
      }
    ]
  }
}'

A criação do pagamento ocorre de forma assíncrona na order. Enquanto está sendo processada, a order é devolvida com o status de processing e sem informações.

Após a conclusão do processamento, e por se tratar de um meio de pagamento offline, a order passa para o status action_required com o detalhe waiting_payment, indicando que o comprador ainda precisa concluir o pagamento no terminal ATM, como mostrado no exemplo de resposta a seguir. Recomendamos configurar as notificações do tópico Order para receber atualizações sobre a mudança de status, incluindo os dados atualizados da order. Alternativamente, você pode optar por enviar uma requisição ao endpoint /v1/orders/{id}GET para consultar o status atualizado.

json
{
  "id": "ORDPE01EXAMPLEPE1234NCAKKBF68N64S",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "description": "Compra de produto 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"
        }
      }
    ]
  }
}

Após criar a order, exiba ao comprador as informações necessárias para concluir o pagamento em um terminal ATM da rede PagoEfectivo. Esses dados estão disponíveis nos campos payment_method da resposta.

O comprador deve utilizar o verification_code e o reference no terminal ATM para concluir o pagamento dentro do prazo de vencimento definido em date_of_expiration.

Depois que o comprador realizar o pagamento, a order passa para status: processed. Se você configurou suas notificações, isso será notificado via webhook.

Caso deseje, você pode cancelar um pagamento criado, desde que esteja pendente ou em processamento. Ou seja, com status=action_required.

Além disso, recomendamos cancelar os pagamentos que não foram realizados dentro da data de vencimento estabelecida, para evitar problemas de cobrança e conciliação.

Para obter mais informações, consulte a seção Reembolsos e cancelamentos.