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 PSE 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 PSE como opção a ser oferecida.

html
Copiar
<form id="form-checkout" action="/process_payment" method="post">
  <div>
    <div>
      <label for="zipCode">Código postal</label>
      <input id="form-checkout__zipCode" name="zipCode" type="text">
    </div>
    <div>
      <label for="streetName">Rua</label>
      <input id="form-checkout__streetName" name="streetName" type="text">
    </div>
    <div>
      <label for="streetNumber">Número</label>
      <input id="form-checkout__streetNumber" name="streetNumber" type="text">
    </div>
    <div>
      <label for="neighborhood">Bairro</label>
      <input id="form-checkout__neighborhood" name="neighborhood" type="text">
    </div>
    <div>
      <label for="city">Cidade</label>
      <input id="form-checkout__city" name="city" type="text">
    </div>
    <div>
      <label for="federalUnit">Departamento</label>
      <input id="form-checkout__federalUnit" name="federalUnit" type="text">
    </div>
    <div>
      <label for="phoneAreaCode">DDD</label>
      <input id="form-checkout__phoneAreaCode" name="phoneAreaCode" type="text">
    </div>
    <div>
      <label for="phoneNumber">Telefone</label>
      <input id="form-checkout__phoneNumber" name="phoneNumber" type="text">
    </div>
    <div>
      <label for="email">E-mail</label>
      <input id="form-checkout__email" name="email" type="text">
    </div>
    <div>
      <label for="personType">Tipo de pessoa</label>
      <select id="form-checkout__personType" name="personType" type="text">
        <option value="natural">Física</option>
        <option value="juridica">Jurídica</option>
      </select>
    </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>
      <label for="banksList">Banco</label>
      <div id="banksList"></div>
    </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
Copiar
document.getElementById('form-checkout__personType').addEventListener('change', e => {
	const personTypesElement = document.getElementById('form-checkout__personType');
	updateSelectOptions(personTypesElement.value);
});

function updateSelectOptions(selectedValue) {

	const naturalDocTypes = [
		new Option('C.C', 'CC'),
		new Option('C.E.', 'CE'),
		new Option('Pasaporte', 'PAS'),
		new Option('Tarjeta de Extranjería', 'TE'),
		new Option('Tarjeta de Identidad ', 'TI'),
		new Option('Registro Civil', 'RC'),
		new Option('Documento de Identificación', 'DI')
	];
	const juridicaDocTypes = [
		new Option('NIT', 'NIT')
	];
	const idDocTypes = document.getElementById('form-checkout__identificationType');

	if (selectedValue === 'natural') {
		idDocTypes.options.length = 0;
		naturalDocTypes.forEach(item => idDocTypes.options.add(item, undefined));
	} else {
		idDocTypes.options.length = 0;
		juridicaDocTypes.forEach(item => idDocTypes.options.add(item, undefined));
	}
}

Ao criar um pagamento com PSE, é necessário enviar o código do banco que será utilizado para a transferência. Para isso, é preciso listar os bancos disponíveis e apresentar essas opções ao pagador, permitindo que ele escolha o banco de sua preferência.

Envie um GET com seu Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. ao endpoint /v1/payment_methodsAPI ou, se preferir, faça a requisição utilizando nossos SDKs abaixo.

<?php
  use MercadoPago\MercadoPagoConfig;

  MercadoPagoConfig::setAccessToken("<YOUR_ACCESS_TOKEN>");

  $client = new PaymentMethodClient();
  $payment_method = $client->get();

?>

import { MercadoPagoConfig, PaymentMethods } from 'mercadopago';

const client = new MercadoPagoConfig({ accessToken: 'access_token' });
const paymentMethods = new PaymentMethods(client);

paymentMethods.get().then((result) => console.log(result))
  .catch((error) => console.log(error));

MercadoPagoConfig.setAccessToken("<YOUR_ACCESS_TOKEN>");

PaymentMethodClient client = new PaymentMethodClient();
client.list();

require 'mercadopago'
sdk = Mercadopago::SDK.new('<YOUR_ACCESS_TOKEN>')

payment_methods_response = sdk.payment_methods.get()
payment_methods = payment_methods_response[:response]

using MercadoPago.Client.PaymentMethod;
using MercadoPago.Config;
using MercadoPago.Resource;
using MercadoPago.Resource.PaymentMethod;

MercadoPagoConfig.AccessToken = "<YOUR_ACCESS_TOKEN>";

var client = new PaymentMethodClient();
ResourcesList<PaymentMethod> paymentMethods = await client.ListAsync();

import mercadopago
sdk = mercadopago.SDK("ACCESS_TOKEN")

payment_methods_response = sdk.payment_methods().list_all()
payment_methods = payment_methods_response["response"]

curl -X GET \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
    'https://api.mercadopago.com/v1/payment_methods' \

A resposta retornará os meios de pagamento, onde você poderá listar os bancos disponíveis para pagamentos com PSE através do campo financial_institutions dentro do objeto com id=pse, conforme exemplo abaixo.

json
Copiar
[
  {
       "id": "pse",
       "name": "PSE",
       "payment_type_id": "bank_transfer",
       "status": "active",
       "secure_thumbnail": "https://www.mercadopago.com/org-img/MP3/API/logos/pse.gif",
       "thumbnail": "https://www.mercadopago.com/org-img/MP3/API/logos/pse.gif",
       "deferred_capture": "does_not_apply",
       "settings": [],
       "additional_info_needed": [
           "entity_type"
       ],
       "min_allowed_amount": 1600,
       "max_allowed_amount": 340000000,
       "accreditation_time": 30,
       "financial_institutions": [
           {
               "id": "1040",
               "description": "Banco Agrario"
           },
           {
               "id": "1507",
               "description": "NEQUI"
           },
           {
               "id": "1052",
               "description": "Banco AV Villas"
           },
           {
               "id": "1032",
               "description": "Banco Caja Social"
           }
       ],
       "processing_modes": [
           "aggregator"
       ]
   }
]

Em seguida, crie um elemento select em JavaScript e enriqueça-o com os dados retornados nessa requisição, como mostra o exemplo abaixo.

javascript
Copiar
function setPse() {
  fetch('/payment_methods')
    .then(async function(response) {
      const paymentMethods = await response.json();
      const pse = paymentMethods.filter((method) => method.id === 'pse')[0];
      const banksList = pse.financial_institutions;
      const banksListElement = document.getElementById('banksList');
      const selectElement = document.createElement('select');
      selectElement.name = 'financialInstitution';

      banksList.forEach(bank => {
        const option = document.createElement('option');
        option.value = bank.id;
        option.textContent = bank.description;
        selectElement.appendChild(option);
      });

      banksListElement.appendChild(selectElement);
    }).catch(function(reason) {
      console.error('Failed to get payment methods', reason);
    });
}

Para que os elementos dinâmicos criados com esse JavaScript sejam carregados quando a página terminar de renderizar, adicione o seguinte código:

javascript
Copiar
(function initCheckout() {
  try {
    const docTypeElement = document.getElementById('form-checkout__identificationType');
    setPse();
    updateSelectOptions('natural')
  } catch(e) {
    return console.error('Error getting identificationTypes: ', e);
  }
})();

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 um POST com seu Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. e os parâmetros requeridos listados abaixo para o endpoint /v1/ordersAPI e execute a requisição.

curl
Copiar
curl --location --request POST 'https://api.mercadopago.com/v1/orders' \
    -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
    -H 'X-Idempotency-Key: <SOME_UNIQUE_VALUE>' \
    -H 'Content-Type: application/json' \
    -d '{
  "type": "online",
  "total_amount": "5000",
  "external_reference": "ext_ref_1234",
  "processing_mode": "automatic",
  "expiration_time": "PT20M",
  "payer": {
    "email": "test_user_co@testuser.com",
    "entity_type": "individual",
    "identification": {
      "type": "NIT",
      "number": "76262349"
    },
    "first_name": "John",
    "last_name": "Doe",
    "phone": {
      "area_code": "57",
      "number": "3001234567"
    },
    "address": {
      "street_name": "Calle 10",
      "street_number": "100",
      "city": "Bogota",
      "zip_code": "110111",
      "neighborhood": "Centro"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": "5000",
        "payment_method": {
          "id": "pse",
          "type": "bank_transfer",
          "financial_institution": "1051"
        }
      }
    ]
  },
  "additional_info": {
    "payer.ip_address": "200.100.50.25"
  },
  "config": {
    "online": {
      "callback_url": "https://merchant.com/pse/return"
    }
  }
}'

Veja na tabela abaixo as descrições dos parâmetros que são obrigatórios na requisição e daqueles que, embora sejam opcionais, possuem alguma particularidade importante de ser destacada.

A resposta retornará o parâmetro redirect_url, que contém a URL com as instruções para que o comprador efetue o pagamento. Você deve redirecioná-lo para essa página, seguindo as orientações da etapa de Disponibilizar pagamento. Além disso, mostrará o status action_required com status_detail=waiting_transfer até que o pagamento seja realizado.

json
Copiar
{
  "id": "ORDOMG01KNSWP75YHQJ9EKKB13QCFF25",
  "total_amount": "5000",
  "total_paid_amount": "0",
  "status": "action_required",
  "status_detail": "waiting_transfer",
  "config": {
    "online": {
      "callback_url": "https://merchant.com/pse/return"
    }
  },
  "transactions": {
    "payments": [
      {
        "payment_method": {
          "id": "pse",
          "type": "bank_transfer",
          "financial_institution": "1051",
          "redirect_url": "https://www.mercadopago.com.co/sandbox/payments/154019160992/bank_transfer?caller_id=2676136474&hash=fd05e480-3f06-4f41-90dc-b6910946e196"
        }
      }
    ]
  }
}

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

Após a criação do pagamento, e para que o cliente possa realizar a transferência, é necessário redirecioná-lo para a URL retornada na resposta à criação da order sob o parâmetro redirect_url.

json
Copiar
{
  [...]
  "transactions": {
    "payments": [
      {
        "payment_method": {
          "id": "pse",
          "type": "bank_transfer",
          "financial_institution": "1051",
          "redirect_url": "https://www.mercadopago.com.co/sandbox/payments/154019160992/bank_transfer?caller_id=2676136474&hash=fd05e480-3f06-4f41-90dc-b6910946e196"
        }
      }
    ]
  }
}

Para isso, você tem duas opções:

• Realizar esse redirecionamento automaticamente após a criação do pagamento.
• Disponibilizar essa URL ao usuário por meio de um botão clicável, seguindo o exemplo abaixo.

html
Copiar
<a href="https://www.mercadopago.com.co/payments/154019160992/bank_transfer?caller_id=2676136474&hash=fd05e480-3f06-4f41-90dc-b6910946e196" target="_blank">Pagar com PSE</a>

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.