Transferências SPEI

Com o Checkout API do Mercado Pago, também é possível oferecer pagamentos por meio de Transferências SPEI, serviço que permite realizar pagamentos de qualquer banco ou instituição financeira utilizando a CLABE (Clave Bancaria Estandarizada).

Se você já configurou seu ambiente e quer oferecer pagamentos via Pix, siga os passos abaixo.

Lembre-se: antes de configurar os meios de pagamento, escolha o modo em que irá processar as suas transações. A definição do modo de processamento, seja manual ou automático, será realizada no momento da criação da order, por meio do parâmetro processing_mode. Para mais informações, acesse a seção Modelo de integração.

Adicionar formulário de pagamento

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 Transferências SPEI entre as opções de pagamento que deseja oferecer, conforme indicado abaixo, e continue para a etapa de Enviar pagamento.

Caso ainda não tenha um formulário de pagamento, adicione o modelo abaixo ao seu projeto e inclua o identificador do Pix como opção a ser oferecida.

Meio de pagamento	`payment_method_id`
Transferência SPEI	`clabe`

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>

Enviar pagamento

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

A criação de um pagamento pode ocorrer de forma assíncrona em uma order. Nesse cenário, a order fica com o status de processando e sem informações. 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 um GET ao endpoint /v1/orders/{id} para buscar esses dados atualizados.

Para isso, envie um POST com seu Access Token produtivoChave privada da aplicação criada no Mercado Pago e que é utilizada no backend em ambientes de desenvolvimento e para receber pagamentos reais. Você pode acessá-la através de Suas integrações > Detalhes da aplicação > Produção > Credenciais de produção. e os parâmetros requeridos listados abaixo para o endpoint /v1/ordersAPI e execute a requisição.

curl
curl --location 'https://api.mercadopago.com/v1/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ENV_ACCESS_TOKEN' \
--header 'X-Idempotency-Key: <SOME_UNIQUE_VALUE>' \
{
  "type": "online",
  "external_reference": "ext_ref_1234",
  "processing_mode": "automatic",
  "total_amount": "200.00",
  "payment_expiration_time": "P3D",
  "payer": {
    "email": "test@testuser.com",
  },
  "transactions": {
    "payments": [
      {
        "amount": "200.00",
        "payment_method": {
          "id": "clabe",
          "type": "bank_transfer"
        }
      }
    ]
  }
}

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.

Atributo	Tipo	Descrição	Obrigatório/Opcional
`Authorization`	Header	Faz referência a sua chave privada, o Access TokenChave privada da aplicação criada no Mercado Pago e que é utilizada no backend em ambientes de desenvolvimento e para receber pagamentos reais. Você pode acessá-la através de Suas integrações > Detalhes da aplicação > Produção > Credenciais de produção..	Obrigatório
`X-Idempotency-Key`	Header	Chave de idempotência. Essa chave garante que cada solicitação seja processada apenas uma vez, evitando duplicidades. Use um valor exclusivo no `header` da requisição, como um UUID V4 ou uma string aleatória.	Obrigatório
`processing_mode`	Body. String	Modo de processamento da order. Os valores possíveis são: - `automatic`: para criar e processar a ordem em modo automático. - `manual`: para criar a order e processá-la posteriormente. Para mais informações, acesse a seção Modelo de integração.	Obrigatório
`total_amount`	Body. String	Valor total da transação.	Obrigatório
`payment_expiration_time`	Body. String	Permite definir a data de vencimento utilizando o formato de duração ISO 8601. Embora você possa configurá-la para ser entre 1 e 30 dias após a emissão do pagamento, recomendamos estabelecer uma duração de 3 dias (“P3D” no exemplo) para evitar conflitos entre o vencimento e a acreditação do pagamento, que pode demorar até 2 horas úteis a partir de sua realização. Em caso de que o pagamento seja realizado após a data de vencimento estabelecida, o valor será devolvido à conta do Mercado Pago do pagador.	Opcional
`payer.email`	Body. String	E-mail do comprador.	Obrigatório
`transaction.payments.payment_method.id`	Body. String	Identificador do meio de pagamento. Neste caso, o valor deverá ser `clabe`.	Obrigatório
`transaction.payments.payment_method.type`	Body. String	Tipo do meio de pagamento. No caso de pagamentos com Pix, o valor deverá ser `bank_transfer`.	Obrigatório

Para conhecer em detalhe todos os parâmetros enviados e retornados nesta requisição, consulte nossa Referência de API. Além disso, caso receba um erro ao enviar o pagamento, consulte nossa lista de erros para mais informações. A resposta retornará o parâmetro ticket_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 até que o pagamento seja realizado.

json
{
  "id": "ORD01J6TC8BYRR0T4ZKY0QR39WGYE",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "marketplace": "NONE",
  "total_amount": "200.00",
  "country_code": "MEX",
  "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",
        "amount": "200.00",
        "reference_id": "22dvqmsbq8c",
        "status": "action_required",
        "status_detail": "waiting_payment",
        "payment_method": {
          "id": "clabe",
          "type": "bank_transfer",
          "ticket_url": "https://www.mercadopago.com.mx/sandbox/payments/00000000000/ticket?caller_id=77777777777&hash=34cb0d7c-81d9-478c-92a5-767d0kakjja",
          "reference": "1234567890"
        }
      }
    ]
  }
}

Caso tenha criado a order em modo manual, lembre-se de que o processamento do pagamento requer uma etapa adicional, a chamada ao endpoint Processar orderAPI.

Disponibilizar pagamento

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 do pedido sob o parâmetro ticket_url.

json
{
  [...]
  "transactions": {
    "payments": [
      {
	  [...]
        "payment_method": {
          "id": "clabe",
          "type": "bank_transfer",
          "ticket_url": "https://www.mercadopago.com.mx/payments/113775986440/ticket?caller_id=1872745950&hash=9545e05b-a530-4c82-9441-a666d0c73f70",
          "reference": "646010349353743569"
        }
      }
    ]
  }
}

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

Realizar esse redirecionamento automaticamente.
Disponibilizar essa URL ao usuário por meio de um botão clicável, seguindo o exemplo abaixo.

html
<a href="https://www.mercadopago.com.mx/payments/51096146182/ticket?caller_id=34728475&hash=f3a8630a-f06a-48e4-b2a6-f95750af7346" target="_blank">Pagar com Transferências SPEI</a>

Cancelar pagamento

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.

Se passarem 30 dias após a data de vencimento estabelecida para um pagamento e este não tiver sido realizado, o Mercado Pago o considerará expirado. Nesses casos, não é possível fazer um cancelamento manual, e o status do pagamento passará a ser cancelado ou expirado.

Para obter mais informações, consulte a seção Reembolsos e cancelamentos.

Informações adicionais sobre notificações

Acesse informações extras sobre tópicos de notificação, especificações de produtos e muito mais.

Documentação

Começando agora?

Recursos

Suporte

Parcerias

Comunidade

Transferências SPEI

Navegação

Recursos e Comunidade

Mercado Pago

País e idioma