Pular para o conteúdo principal
A Localpayment permite que comerciantes processem pagamentos instantâneos por meio do sistema Pix, a plataforma revolucionária de pagamentos instantâneos do Brasil, desenvolvida pelo Banco Central do Brasil. Este guia descreve o processo para iniciar pagamentos Pix por meio da API da Localpayment, detalhando os parâmetros necessários, o tratamento de respostas e a interpretação de códigos de status para uma integração perfeita com a infraestrutura de pagamentos em tempo real do Brasil. O Pix é o sistema de pagamentos instantâneos do Brasil, desenvolvido pelo Banco Central do Brasil (BCB). Ele permite que pessoas físicas e jurídicas enviem e recebam pagamentos em segundos, 24 horas por dia, 7 dias por semana, 365 dias por ano. O Localpayment oferece suporte a dois métodos principais de pagamento Pix:
  • Código QR Pix: Os clientes escaneiam um código QR dinâmico com o aplicativo bancário.
  • Pix Copiar e Colar (Copia e Cola): Os clientes copiam um código Pix e colam-no na aplicação do seu banco ou carteira digital para iniciar a transferência.
Ambos os métodos utilizam o mesmo endpoint da API e proporcionam uma experiência de pagamento rápida e segura.

Antes de começar

Certifique-se de ter:

Passo 1. Criar pagamento Pix

Para gerar um pagamento Pix para cobrança no Brasil, envie uma solicitação POST ao endpoint Criar Payin com parâmetros específicos do Pix.

Parâmetros-chave da solicitação

A solicitação requer vários objetos-chave específicos para pagamentos por QR Code: Veja todos os parâmetros disponíveis na solicitação.
O mesmo endpoint serve para ambos os métodos: esta única requisição à API é usada para gerar um pagamento tanto para o Pix QR Code quanto para o Pix Copy and Paste (Copia e Cola). O método usado pelo cliente é determinado pela forma como você apresenta os detalhes do pagamento retornados na resposta.

Exemplo de solicitação

Abaixo está um exemplo usando curl:
curl

Etapa 2. Lidar com a resposta

Resposta bem-sucedida

A criação bem-sucedida de um pagamento Pix inclui os dados do código Pix e os detalhes do pagamento:

Campos de resposta principais

Resposta de erro

Quando a geração do Pix falhar para o Brasil, você receberá informações de erro específicas:

Etapa 3. Apresente o pagamento Pix

Você pode apresentar o pagamento Pix ao seu cliente de duas maneiras. A resposta da API fornece os dados necessários para ambas.

Opção A: Exibir como um código QR

  1. Renderize o código QR: Use a sequência do campo qr.code na resposta da API para gerar uma imagem de código QR que possa ser escaneada, usando qualquer biblioteca de QR Code.
  2. Escaneamento pelo cliente: O cliente escaneia o código QR com o aplicativo do banco.
  3. Autorizar: O cliente confirma os detalhes do pagamento e autoriza a transferência dentro do aplicativo.
  4. Confirmação em tempo real: o Localpayment recebe notificação de pagamento instantaneamente.
  5. Atualização de status: Seu sistema recebeu um webhook com a confirmação de pagamento.

Melhores práticas para exibição de QR Code

  • Tamanho mínimo de exibição: 250x250 pixels para digitalização em dispositivos móveis.
  • Mantenha a proporção de 1:1 sem distorção.
  • Garanta alto contraste (escuro sobre fundo claro).
  • Adicione uma zona de silêncio (borda branca) ao redor do código QR.
  • Inclua um texto alternativo (ex.: “Pagamento por código QR”).
  • Exibir instruções de pagamento claras.
  • Gerenciar o tempo de vida (TTL) e a expiração.

Opção B: Exibir como um código para copiar e colar (Copia e Cola)

  1. Apresente o código: Exiba a sequência completa do campo qr.code ao seu cliente como texto selecionável.
  2. O cliente copia e cola o código: o cliente copia todo o código e abre o aplicativo do banco ou da carteira digital.
  3. Colar e pagar: O cliente cola o código no campo “Pagar com código Pix” ou similar do aplicativo para carregar os detalhes do pagamento.
  4. Autorizar: O cliente analisa e autoriza a transferência.
  5. Confirmação em tempo real: o Localpayment recebe notificação de pagamento instantaneamente.
  6. Atualização de status: Seu sistema recebeu um webhook com a confirmação de pagamento.


Etapa 4. Acompanhe o status da transação

Acompanhe o progresso dos pagamentos da Pix por meio destes métodos:

Webhooks (Recomendado)

Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

Endpoint da API de Status

Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

Visualização do Business Portal

Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

Códigos de status comuns

A API Localpayment fornece vários códigos de status para indicar o progresso e o resultado do pagamento na resposta.
Referência completaConsulte todos os códigos de status em nossa Documentação de Status da Transação.

Testando sua integração

Ambiente de Sandbox

Utilize o ambiente de teste para realizar os procedimentos:

Cenários de teste de QR Code

Verifique se sua integração lida com esses cenários:
  1. Pagamento efetuado com sucesso: Conclua o pagamento da Pix com liquidação instantânea.
  2. Validade do QR Code: Lide com pagamentos Pix expirados de forma adequada.
  3. Múltiplas tentativas de pagamento: o mesmo código QR foi lido várias vezes.
  4. Atualizações de status: gerenciamento de webhooks e consulta de status.

Próximos passos

Após implementar os pagamentos Pix, considere estas funcionalidades adicionais:

Reembolsar a transação

Caso necessário, você pode reembolsar o pagamento ao cliente. Consulte a documentação para obter detalhes.

Analisar detalhes da transação

Você pode obter informações detalhadas sobre as transações usando a API Localpayment.
Última modificação em 10 de novembro de 2026