Para poder recibir pagos, es necesario que añadas en el frontend un formulario que permita capturar los datos del pagador de manera segura.

Si ya cuentas con un desarrollo que contempla un formulario de pago propio, asegúrate de incluir Pix entre las opciones de pago que deseas ofrecer, como es indicado a continuación, y avanza a la etapa de Obtener tipos de documento.

Si no cuentas con un formulario de pago, añade el siguiente a tu proyecto, incluyendo el identificador de Pix como medio de pago a ofrecer.

html
Copiar
<form id="form-checkout" action="/process_payment" method="post">
    <div>
      <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" type="text"></select>
      </div>
      <div>
        <label for="identificationNumber">Número do documento</label>
        <input id="form-checkout__identificationNumber" name="identificationNumber" type="text">
      </div>
    </div>

    <div>
      <div>
        <input type="hidden" name="transactionAmount" id="transactionAmount" value="100">
        <input type="hidden" name="description" id="description" value="Nome do Produto">
        <br>
        <button type="submit">Pagar</button>
      </div>
    </div>
  </form>

Para facilitar la inserción de datos en el formulario de pago de manera correcta, es necesario obtener los posibles tipos de documento a ser aceptados.

La función a continuación te permitirá completar automáticamente las opciones disponibles. Para eso, basta incluir el elemento select con el id: form-checkout__identificationType que se encuentra en el formulario utilizado como ejemplo en la etapa anterior.

Si ya cuentas con un desarrollo que contempla la obtención de tipos de documento, como es indicado a continuación, avanza a la etapa de Enviar pago.

Si no cuentas con esta función, añade la siguiente a tu proyecto.

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

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

    function createSelectOptions(elem, options, labelsAndKeys = { label: "name", value: "id" }) {
      const { label, value } = labelsAndKeys;

      elem.options.length = 0;

      const tempOptions = document.createDocumentFragment();

      options.forEach(option => {
        const optValue = option[value];
        const optLabel = option[label];

        const opt = document.createElement('option');
        opt.value = optValue;
        opt.textContent = optLabel;

        tempOptions.appendChild(opt);
      });

      elem.appendChild(tempOptions);
    }

El envío del pago debe ser realizado mediante la creación de una order que contenga transacciones de pago asociadas.

Para eso, envía un POST con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación > Pruebas > Credenciales de prueba. y los parámetros requeridos enumerados a continuación al endpoint /v1/ordersAPI y ejecutes la requisición.

curl
Copiar
curl -X POST \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
    -H 'X-Idempotency-Key: SOME_UNIQUE_VALUE' \
    'https://api.mercadopago.com/v1/orders' \
    -d '{
  "type": "online",
  "total_amount": "1000.00",
  "external_reference": "ext_ref_1234",
  "processing_mode": "automatic",
  "transactions": {
    "payments": [
      {
        "amount": "1000.00",
        "payment_method": {
          "id": "pix",
          "type": "bank_transfer"
        },
        "expiration_time": "P3Y6M4DT12H30M5S"
      }
    ]
  },
  "payer": {
    "email": "test@testuser.com"
  }
}'

Consulte en la tabla a continuación las descripciones de los parámetros que son obligatorios en la solicitud y aquellos que, aunque son opcionales, tienen alguna particularidad importante que debe destacarse.

json
Copiar
{
  "id": "ORD01HRYFWNYRE1MR1E60MW3X0T2P",
  "type": "online",
  "total_amount": "1000.00",
  "external_reference": "ext_ref_1234",
  "country_code": "BRA",
  "status": "action_required",
  "status_detail": "waiting_transfer",
  "capture_mode": "automatic",
  "transactions": {
    "payments": [
      {
        "id": "PAY01HRYFXQ53Q3JPEC48MYWMR0TE",
        "reference_id": "123456789",
        "status": "action_required",
        "status_detail": "waiting_transfer",
        "amount": "1000.00",
        "payment_method": {
          "id": "pix",
          "type": "bank_transfer",
          "ticket_url": "https://www.mercadopago.com.br/sandbox/payments/00000000000/ticket?caller_id=77777777777&hash=34cb0d7c-81d9-478c-92a5-767d0kakjja",
          "qr_code": "00020126580014br.gov.bcb.pix0136b76aa9c2-2ec4-4110-954e-ebfe34f05b61520400005303986540510.005802BR5912TESTPVBWOSBE6009Sao Paulo62240520mpqrinter715936942186304C3C0",
          "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAABWQAAAVkAQAAAAB79i"
        }
      }
    ]
  },
  "processing_mode": "automatic",
  "marketplace": "NONE"
}

Entre los parámetros devueltos, tenemos los indicados en la tabla a continuación.

Después de crear la solicitud de pago con Pix, elige la forma en que el usuario podrá realizarlo, que puede ser a través de un link o botón de pago o de un QR Code renderizado.

Selecciona la opción que mejor se adapte a tu modelo de negocio y sigue los pasos descritos a continuación.

Al optar por agregar un link o botón para el pago con Pix, el comprador será dirigido a una nueva ventana que contiene toda la información para realizar el pago, como el QR Code o Pix Copia e Cola, y sus respectivas instrucciones.

Para ofrecer esta opción, utiliza el atributo ticket_url, devuelto en la respuesta de la solicitud, como se presenta a continuación:

html
Copiar
<a href="https://www.mercadopago.com.br/payments/123456789/ticket?caller_id=123456&hash=123e4567-e89b-12d3-a456-426655440000" target="_blank">Pagar com Pix</a>

Es posible renderizar el QR Code vigente, devuelto en la respuesta de la solicitud y que debe ser utilizado solo una vez, en la propia pantalla de pago. Además, también es posible agregar una opción para copiar y pegar el código de pago, lo que permitirá realizar la transacción a través de Internet Banking.

Para ello, sigue los pasos a continuación.

1. Agrega el qr_code_base64, devuelto en la respuesta de la solicitud, para mostrar el QR Code.

html
Copiar
<img src={`data:image/jpeg;base64,${qr_code_base64}`}/>

2. Luego, agrega el qr_code, devuelto en la respuesta de la solicitud, para presentar la opción que permitirá copiar y pegar el código.

html
Copiar
<label for="copiar">Copiar Hash:</label>
<input type="text" id="copiar" value={qr_code} readonly/>

Al completar estos pasos, se mostrará al comprador el QR Code renderizado junto con la opción de copiar y pegar su código de pago.

Si lo deseas, puedes cancelar un pago creado para boleto bancário, 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.