Rapipago e Pago Fácil

Para receber pagamentos, é necessário adicionar no frontend um formulário que permita capturar os dados do pagador de maneira segura.

Se você já tem um desenvolvimento que inclui um formulário de pagamento próprio, certifique-se de incluir Rapipago e Pago Fácil entre as opções de pagamento que deseja oferecer, conforme indicado abaixo, e continue para a etapa de Obter tipos de documento.

Caso ainda não tenha um formulário de pagamento, adicione o modelo abaixo ao seu projeto e inclua o identificador do meio de pagamento a ser oferecido.

html
<form id="form-checkout" action="/process_payment" method="post">
    <div>
      <div>
        <label for="payerFirstName">Nombre</label>
        <input id="form-checkout__payerFirstName" name="payerFirstName" type="text">
      </div>
      <div>
        <label for="payerLastName">Appelido</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 del 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 o preenchimento correto do formulário de pagamento, é preciso obter os tipos de documento que podem ser aceitos.

A função abaixo permite completar automaticamente as opções disponíveis. Para isso, basta incluir no formulário o elemento select com o id=form-checkout__identificationType, utilizado no exemplo da etapa anterior.

Se você já possui um desenvolvimento que contempla a obtenção de tipos de documento, como indicado a seguir, avance para a etapa de Enviar pagamento.

Caso ainda não tenha essa função, adicione o código a seguir ao seu projeto.

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

O envio do pagamento deve ser realizado mediante a criação de uma order que contenha a transação de pagamento associada.

Para isso, envie uma requisição com seu Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e começa com o prefixo `APP_USR`. e os parâmetros requeridos listados abaixo ao endpoint /v1/ordersPOST.

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": "50.00",
  "payer": {
    "email": "test_payer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "identification": {
      "type": "DNI",
      "number": "99999999999"
    }
  },
  "config": {
    "location": {
      "state_id": "AR-B"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": "50.00",
        "expiration_time": "P3D",
        "payment_method": {
          "id": "rapipago",
          "type": "ticket"
        }
      }
    ]
  }
}'

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, 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": "ORD01J6TC8BYRR0T4ZKY0QR39WGYE",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "country_code": "ARG",
  "user_id": "1245621468",
  "status": "action_required",
  "status_detail": "waiting_payment",
  "capture_mode": "automatic",
  "created_date": "2024-09-02T22:04:01.880469Z",
  "last_updated_date": "2024-09-02T22:04:04.429289Z",
  "integration_data": {
    "application_id": "4599991948843755"
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J6TC8BYRR0T4ZKY0QRTZ0E24",
        "reference_id": "22dvqmsbq8c",
        "amount": "50.00",
        "status": "action_required",
        "status_detail": "waiting_payment",
        "payment_method": {
          "id": "rapipago",
          "type": "ticket",
          "ticket_url": "https://www.mercadopago.com.ar/payments/86797024510/ticket?caller_id=1870026883&payment_method_id=rapipago&payment_id=86797024510&payment_method_reference_id=6004835002&hash=0331521a-9ddb-44a2-851c-65f77d8d394e",
          "barcode_content": "3335008800000000006004835002100020000242462010",
          "reference": "6005407530",
          "verification_code": "6005407530"
        }
      }
    ]
  }
}

Dentre os parâmetros retornados, temos os indicados na tabela abaixo.

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.