- 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.
Antes de começar
Certifique-se de ter:- Credenciais de API válidas (token de acesso).
Passo 1. Criar pagamento Pix
Para gerar um pagamento Pix para cobrança no Brasil, envie uma solicitaçãoPOST 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 usandocurl:
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
- Renderize o código QR: Use a sequência do campo
qr.codena resposta da API para gerar uma imagem de código QR que possa ser escaneada, usando qualquer biblioteca de QR Code. - Escaneamento pelo cliente: O cliente escaneia o código QR com o aplicativo do banco.
- Autorizar: O cliente confirma os detalhes do pagamento e autoriza a transferência dentro do aplicativo.
- Confirmação em tempo real: o Localpayment recebe notificação de pagamento instantaneamente.
- 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)
- Apresente o código: Exiba a sequência completa do campo
qr.codeao seu cliente como texto selecionável. - 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.
- 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.
- Autorizar: O cliente analisa e autoriza a transferência.
- Confirmação em tempo real: o Localpayment recebe notificação de pagamento instantaneamente.
- 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:- Pagamento efetuado com sucesso: Conclua o pagamento da Pix com liquidação instantânea.
- Validade do QR Code: Lide com pagamentos Pix expirados de forma adequada.
- Múltiplas tentativas de pagamento: o mesmo código QR foi lido várias vezes.
- 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.

