Pix

To be able to receive payments, you need to add a form in the frontend that securely captures the payer's information.

If you already have a development that includes your own payment form, make sure to include Pix among the payment options you want to offer, as indicated below, and continue to the next step.

If you do not have a payment form, add the form below to your project, including the identifier for boleto bancário among the payment methods to be offered.

html
<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>

To facilitate the correct entry of data in the payment form, it is necessary to obtain the possible document types to be accepted.

The function below will allow you to automatically populate the available options, thanks to the inclusion of the select element with the id: form-checkout__identificationType found in the form used as an example in the previous step.

If you already have a development that includes the retrieval of document types, as indicated below, proceed to Submit payment.

If you do not have this function, add the following to your project.

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

The payment submission must be made by creating an order that contains associated payment transactions.

To do this, send a request with your test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the frontend, and starts with the `APP_USR` prefix. and the required parameters listed below to the endpoint /v1/ordersPOST.

curl
curl -X POST \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
    -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
    'https://api.mercadopago.com/v1/orders' \
    -d '{
  "type": "online",
  "total_amount": "50.00",
  "external_reference": "ext_ref_1234",
  "processing_mode": "automatic",
  "config": {
    "location": {
      "state_id": "BR-SP"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": "50.00",
        "payment_method": {
          "id": "pix",
          "type": "bank_transfer"
        },
        "expiration_time": "P3Y6M4DT12H30M5S"
      }
    ]
  },
  "payer": {
    "email": "test_payer@example.com"
  }
}'

See the table below for descriptions of the parameters that are mandatory in the request and those that, although optional, have some important particularity that should be highlighted.

The response will return the parameters ticket_url, qr_code and qr_code_base64, containing, respectively, the URL with instructions for the buyer to complete the payment, an alphanumeric code to be used in the configuration to display the option that will allow copying and pasting the payment code, and the QR code that can be rendered directly on the payment screen. You must make one or all of these options available following the guidelines in the Make the payment available step. Additionally, it will also display the status action_required with status_detail=waiting_transfer until the payment is made.

json
{
  "id": "ORD01HRYFWNYRE1MR1E60MW3X0T2P",
  "type": "online",
  "total_amount": "50.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": "50.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"
}

Among the returned parameters, we have those indicated in the table below.

After creating the payment request with Pix, choose how the user will be able to make the payment on the frontend, either through a payment link or button or a rendered QR code.

Select the option that best fits your business model and follow the steps described below.

Add link or bottom

When choosing to add a link or button for payment with Pix, the buyer will be directed to a new window containing all the information to complete the payment, such as QR code or Pix Copia e Cola, along with the respective payment instructions.

To offer this option, use the ticket_url attribute returned in the response of the request, as shown below:

html
<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>

Render QR code

It is possible to render the current QR code returned in the response of the request, which should be used only once, on the payment screen itself. Additionally, you can also add an option to copy and paste the payment code, allowing the transaction to be carried out via Internet Banking.

To do this, follow the steps below.

1. Add the qr_code_base64, returned in the response of the request, to display the QR code.

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

2. Next, add the qr_code, returned in the response of the request, to present the option that allows copying and pasting the code.

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

Once these steps are completed, the buyer will see the rendered QR code along with the option to copy and paste their payment code at the time of payment.

If you wish, you can cancel a payment created, as long as it is pending or in process; that is, with status=action_required.

Additionally, we recommend canceling payments that were not made by the established due date to avoid billing and reconciliation issues.

For more information, please consult the Refunds and cancellations section.