Outros meios de pagamento - Configuração da integração - Mercado Pago Developers

Não sabe como começar a integrar?

Outros meios de pagamento

Com o Checkout Transparente do Mercado Pago, é possível oferecer, além de cartão e Pix, pagamentos através de boleto bancário e pagamento em lotérica.

Importante

Além das opções disponíveis nesta documentação, também é possível integrar outros meios de pagamento utilizando o Brick de Payment. Veja a documentação Renderização padrão de Payment para mais detalhes.

Para obter uma lista detalhada com todos os meios de pagamento disponíveis para integração, envie um GET com seu Access token ao endpoint /v1/payment_methods e execute a requisição ou, se preferir, faça a requisição utilizando os SDKs abaixo.

          
<?php
  use MercadoPago\MercadoPagoConfig;

  MercadoPagoConfig::setAccessToken("ENV_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("ENV_ACCESS_TOKEN");

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

          
require 'mercadopago'
sdk = Mercadopago::SDK.new('ENV_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 = "ENV_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 ENV_ACCESS_TOKEN' \
    'https://api.mercadopago.com/v1/payment_methods' \

Para oferecer pagamentos com boleto bancário e/ou pagamento em lotérica, siga as etapas abaixo.

Importar MercadoPago.js

Para realizar a integração do Checkout Transparente é preciso capturar os dados necessários para processar o pagamento.

Esta captura é feita a partir da inclusão da biblioteca MercadoPago.js em seu projeto, seguida do formulário de pagamento. Utilize o código abaixo para importar a biblioteca MercadoPago.js antes de adicionar o formulário de pagamento.

          
<body>
  <script src="https://sdk.mercadopago.com/js/v2"></script>
</body>

          
npm install @mercadopago/sdk-js

Configurar credenciais

As credenciais são senhas únicas com as quais identificamos uma integração na sua conta. Servem para capturar pagamentos em lojas virtuais e outras aplicações de forma segura.

Esta é a primeira etapa de uma estrutura completa de código que deverá ser seguida para a correta integração dos pagamentos. Atente-se aos blocos abaixo para adicionar aos códigos conforme indicado.

          
<script>
  const mp = new MercadoPago("YOUR_PUBLIC_KEY");
</script>

          
import { loadMercadoPago } from "@mercadopago/sdk-js";

await loadMercadoPago();
const mp = new window.MercadoPago("YOUR_PUBLIC_KEY");

Adicionar formulário de pagamento

Com a biblioteca MercadoPago.js incluída, adicione o formulário de pagamento abaixo ao seu projeto para garantir a captura segura dos dados dos compradores. Nesta etapa é importante utilizar a lista que você consultou para obter os meios de pagamento disponíveis para criar as opções de pagamento que deseja oferecer.

Importante

Para configurar pagamentos com boleto bancário, é obrigatório que os campos zip_code, street_name, street_number, neighborhood, city e federal_unit estejam presentes no formulário de pagamento e sejam preenchidos pelo comprador. Se você tiver uma configuração que não os inclua, será necessário atualizá-la para garantir que seus pagamentos sejam processados.

          
 <form id="form-checkout" action="/process_payment" method="post">
   <div>
       <h1>Payer Request</h1>
     <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>
       <input id="form-checkout__identificationType" name="identificationType" type="text"></input>
     </div>
     <div>
       <label for="identificationNumber">Número do documento</label>
       <input id="form-checkout__identificationNumber" name="identificationNumber" type="text">
     </div>
     <div>
       <label for="zip_code"> CEP: </label>
       <input id="form-checkout__zip_code" name="zip_code" type="text">
     </div>
     <div>
       <label for="street_name"> Rua: </label>
       <input id="form-checkout__street_name" name="street_name" type="text">
     </div>
     <div>
       <label for="street_number"> Número: </label>
       <input id="form-checkout__street_number" name="street_number" 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="federal_unit"> Estado: </label>
       <input id="form-checkout__federal_unit" name="federal_unit" 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>

Obter tipos de documento

Após configurar a credencial, é preciso obter os tipos de documento que farão parte do preenchimento do formulário para pagamento.

Incluindo o elemento do tipo select com o id: id = docType que está no formulário, será possível preencher automaticamente as opções disponíveis quando chamar a função a seguir:

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

Enviar pagamento

Ao finalizar a inclusão do formulário de pagamento e obter os tipos de documento, é necessário encaminhar o e-mail do comprador, tipo e número de documento, o meio de pagamento utilizado e o detalhe do valor a ser pago utilizando nossa API de Pagamentos ou um de nossos SDKs.

Para configurar pagamentos com boleto bancário ou pagamento em lotérica, envie um POST com os parâmetros descritos nas tabelas abaixo ao endpoint /v1/payments e execute a requisição ou, se preferir, utilize um de nossos SDKs abaixo.

Atenção

Para esta etapa, ao realizar a requisição via API ou SDKs, é necessário enviar sua Chave Privada - Access token. Para mais informações, acesse Credenciais . Além disso, você deverá enviar o header X-Idempotency-Keycom sua chave de idempotência. Seu preenchimento é importante para garantir a execução e reexecução de requisições sem que haja situações indesejadas como, por exemplo, pagamentos em duplicidade.

          
<?php

use MercadoPago\Client\Payment\PaymentClient;
use MercadoPago\Client\Common\RequestOptions;
use MercadoPago\MercadoPagoConfig;

MercadoPagoConfig::setAccessToken("YOUR_ACCESS_TOKEN");

$client = new PaymentClient();
$request_options = new RequestOptions();
$request_options->setCustomHeaders(["X-Idempotency-Key: <SOME_UNIQUE_VALUE>"]);

$payment = $client->create([
  "transaction_amount" => (float) $_POST['<TRANSACTION_AMOUNT>'],
  "payment_method_id" => $_POST['<PAYMENT_METHOD_ID>'],
  "payer" => [
    "email" => $_POST['<EMAIL>'],
    "first_name" => $_POST['<NOME>'],
    "last_name" => $_POST['<SOBRENOME>'],
    "identification" => [
      "type" =>  $_POST['<TIPO DE DOCUMENTO>'],
      "number" => $_POST['<NUMERO>']
    ],
    "address" => [
      "zip_code" => $_POST['<CEP>'],
      "city" => $_POST['<CIDADE>'],
      "street_name" => $_POST['<RUA>'],
      "street_number" => $_POST['<NÚMERO>'],
      "neighborhood" => $_POST['<BAIRRO>'],
      "federal_unit" => $_POST['<SIGLA DO ESTADO>']
    ]
  ]
], $request_options);
echo implode($payment);
?>

          
import { MercadoPagoConfig, Payments } from 'mercadopago';

const client = new MercadoPagoConfig({ accessToken: '<YOUR_ACCESS_TOKEN>' });
const payments = new Payments(client);

payments.create({
body: {
       transaction_amount: '<TRANSACTION_AMOUNT>',
       payment_method_id: '<PAYMENT_METHOD_ID>',
       payer: {
           email: '<EMAIL>',
           first_name: '<NOMBRE>',
           last_name: '<APELLIDO>',
           identification:{
               type:'<TIPO DE DOCUMENTO>',
               number:'<NUMERO_DOCUMENTO>'
       },
           address:{
               zip_code: '<CEP>',
               city: '<CIUDAD>',
               neighborhood: '<BARRIO>',
               street_name: '<CALLE>',
               street_number: '<NÚMERO>',
               federal_unit: '<SIGLA ESTADO>'
       }
           }
},
   requestOptions: { idempotencyKey: '<SOME_UNIQUE_VALUE>' }
})
   .then((result) => console.log(result))
   .catch((error) => console.log(error));

          
PaymentCreateRequest paymentCreateRequest = PaymentCreateRequest.builder()
    .transactionAmount(new BigDecimal("<TRANSACTION_AMOUNT>"))
    .paymentMethodId("bolbradesco")
    .payer(PaymentPayerRequest.builder()
        .email("<EMAIL>")
        .firstName("<NAME>")
        .lastName("<LASTNAME>")
        .identification(IdentificationRequest.builder()
            .type("CPF")
            .number("<NUMERO>")
            .build())
        .address(PaymentPayerAddressRequest.builder()
            .streetName("<RUA XXX>")
            .streetNumber("123")
            .zipCode("<CEP>")
            .federalUnit("<SIGLA DO ESTADO>")
            .city("<CIDADE>")
            .neighborhood("<BAIRRO>")
            .build())
        .build())
    .build();

          
require 'mercadopago'
sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN')

custom_headers = {
 'x-idempotency-key': '<SOME_UNIQUE_VALUE>'
}

custom_request_options = Mercadopago::RequestOptions.new(custom_headers: custom_headers)

payment_request = {
  transaction_amount: 100,
  description: 'Título del producto',
  payment_method_id: 'bolbradesco',
  payer: {
    email: 'PAYER_EMAIL',
    first_name: 'Test',
    last_name: 'User',
    identification: {
      type: 'DNI',
      number: '19119119',
    },
    address: {
      zip_code: '1264',
      street_name: 'Av. Caseros',
      street_number: '3039',
      neighborhood: 'Parque Patricios',
      city: 'Buenos Aires',
      federal_unit: 'BA'
    }
  }
}

payment_response = sdk.payment.create(payment_request, custom_request_options)
payment = payment_response[:response]

          
MercadoPagoConfig.AccessToken = "<ENV_ACCESS_TOKEN>";

var request = new PaymentCreateRequest
{
   TransactionAmount = 105,
   Description = "<DESCRIPCIÓN>",
   PaymentMethodId = "bolbradesco",
   Payer = new PaymentPayerRequest
   {
       Email = "<EMAIL>",
       FirstName = "<NOMBRE>",
       LastName = "<APELLIDO>",
       Identification = new IdentificationRequest
       {
           Type = "CPF",
           Number = "<NUMERO DE CPF>",
       },
       Address = new  PaymentPayerAddressRequest
       {
           ZipCode = "<CÓDIGO POSTAL>",
           StreetName = "<CALLE XXX>",
           City = "<CIUDAD>",
           StreetNumber = "<NÚMERO>",
           Neighborhood = "<BARRIO>",
           FederalUnit = "<SIGLA DE ESTADO>",

       }
   },
};
var client = new PaymentClient();
Payment payment = await client.CreateAsync(request);

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

request_options = mercadopago.config.RequestOptions()
request_options.custom_headers = {
    'x-idempotency-key': '<SOME_UNIQUE_VALUE>'
}

payment_data = {
    "transaction_amount": 100,
    "description": "Título del producto",
    "payment_method_id": "bolbradesco",
    "payer": {
        "email": "PAYER_EMAIL",
        "first_name": "Test",
        "last_name": "User",
        "identification": {
            "type": "DNI",
            "number": "19119119"
        },
        "address": {
            "zip_code": "1264",
            "street_name": "Av. Caseros",
            "street_number": "3039",
            "neighborhood": "Parque Patricios",
            "city": "Buenos Aires",
            "federal_unit": "BA"
        }
    }
}

payment_response = sdk.payment().create(payment_data, request_options)
payment = payment_response["response"]

          
accessToken := "{{ACCESS_TOKEN}}"


cfg, err := config.New(accessToken)
if err != nil {
  fmt.Println(err)
  return
}

client := payment.NewClient(cfg)


request := payment.Request{
   TransactionAmount: 105,
   PaymentMethodID:   "bolbradesco",
   Payer: &payment.PayerRequest{
      Email:     "{{EMAIL}}",
      FirstName: "{{NOME}}",
      LastName:  "{{SOBRENOME}}",
      Identification: &payment.IdentificationRequest{
         Type:   "{{TIPO DO DOCUMENTO}}",
         Number: "{{NUMERO}}",
      },
      Address: &payment.AddressRequest{
         ZipCode:      "06233-200",
         City:         "Osasco",
         Neighborhood: "Bonfim",
         StreetName:   "Av. das Nações Unidas",
         StreetNumber: "3003",
         FederalUnit:  "SP",
      },
   },
}


resource, err := client.Create(context.Background(), request)
if err != nil {
   fmt.Println(err)
   return
}


fmt.Println(resource)

          
curl --location 'https://api.mercadopago.com/v1/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ENV_ACCESS_TOKEN' \
--header 'X-Idempotency-Key: <SOME_UNIQUE_VALUE>' \
--header 'X-Product-Id: <SOME_UNIQUE_VALUE>' \
--data-raw '{
   "transaction_amount": 100,
   "description": "Titulo do produto",
   "payment_method_id": "bolbradesco",
   "payer": {
       "email": "test_user_12345@testuser.com",
       "first_name": "Test",
       "last_name": "User",
       "identification": {
           "type": "CPF",
           "number": "01234567890"
       }
       "address": {
           "zip_code": "88000000",
           "street_name": "Nombre de calle",
           "street_number": "123",
           "neighborhood": "Barrio",
           "city": "Ciudad",
           "federal_unit": "UF"
       }
   }
}'

- Campos obrigatórios para pagamentos com boleto bancário

Parâmetro	Tipo	Descrição, valores possíveis e exemplos
`payment_method_id`	string	Método de pagamento. Para boleto, é sempre `bolbradesco`.
`address.zip_code`	string	CEP. Exemplo: 88000000
`address.street_name`	string	Nome da rua do comprador. Exemplo: Rua da Abobrinha.
`address.street_number`	string	Número do endereço do comprador. Exemplo: 1291
`address.neighborhood`	string	Bairro onde está localizado o endereço do comprador. Exemplo: Copacabana.
`address.city`	string	Cidade onde o comprador mora. Exemplo: Rio de Janeiro.
`address.federal_unit`	string	Sigla do Estado onde o comprador mora. Apenas dois caracteres são aceitos. Por exemplo: RJ.

- Campos obrigatórios para pagamentos em lotéricas

Parâmetro	Tipo	Descrição, valores possíveis e exemplos
`payment_method_id`	string	Método de pagamento. Para lotéricas, é sempre `pec`.

Importante

Se precisar de informações adicionais sobre como enviar todos os campos necessários nesta requisição, consulte a Referência da API .

A resposta mostrará o status pendente até que o comprador realize o pagamento. Além disso, na resposta à requisição, o parâmetro external_resource_url retornará uma URL que contém as instruções para que o comprador realize o pagamento. Você pode redirecioná-lo para este mesmo link para conclusão do fluxo de pagamento. Veja abaixo um exemplo de retorno.

          
[
 {
    ...,
    "id": 5466310457,
    "status": "pending",
    "status_detail": "pending_waiting_payment",
    ...,
    "transaction_details": {
        "net_received_amount": 0,
        "total_paid_amount": 100,
        "overpaid_amount": 0,
        "external_resource_url": "https://www.mercadopago.com/mlb/payments/ticket/helper?payment_id=123456789&payment_method_reference_id= 123456789&caller_id=123456",
        "installment_amount": 0,
        "financial_institution": null,
        "payment_method_reference_id": "1234567890"
    }
 }
]

Nota

O cliente tem entre 3 e 5 dias para pagar, dependendo do meio de pagamento. Após esse tempo, o pagamento deve ser cancelado.

Data de vencimento

A data de vencimento padrão para pagamentos com boleto é de 3 dias. Opcionalmente, é possível alterar essa data enviando o campo date_of_expiration na requisição de criação do pagamento definindo um período entre 1 e 30 dias a partir da data de emissão do boleto.

Para alterar a data de vencimento, utilize um dos códigos disponíveis abaixo.