Pular para o conteúdo principal
A Localpayment permite que os comerciantes processem pagamentos instantâneos através do sistema de pagamentos QR Fri da Guatemala, a plataforma de pagamentos QR interoperável e padronizada do país, regulamentada pelo Banco da Guatemala. A Fri (anteriormente conhecida como Soyfri) é uma carteira digital e plataforma de pagamentos que facilita transações rápidas e seguras, permitindo que os usuários vinculem suas contas bancárias ou cooperativas para realizar operações financeiras diretamente de seus dispositivos móveis. Este guia descreve o processo para iniciar pagamentos QR Fri 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 rede de pagamentos unificada da Guatemala. O QR Fri permite que os comerciantes gerem códigos QR dinâmicos via API, que os clientes escaneiam usando o aplicativo Fri, facilitando pagamentos em tempo real diretamente de suas contas bancárias vinculadas por meio da infraestrutura intermediária de pagamentos do Fri.
Os pagamentos via QR Code Fri na Guatemala estão disponíveis através das carteiras digitais Fri e Micoope para pessoas físicas, jurídicas e usuários estrangeiros com números de telefone guatemaltecos. Os bancos suportados incluem GyT, Banrural, Promerica e cooperativas como a Micoope, enquanto o Banco Industrial e o BAC estão atualmente excluídos. Consulte o site oficial do Fri para obter a lista completa de instituições suportadas.

Antes de começar

Certifique-se de ter:

Passo 1. Criar pagamento por QR Code

Para gerar um código QR para cobrança de pagamentos, envie uma solicitação POST ao endpoint Criar Payin com parâmetros específicos de QR Code.

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.

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 por QR Code inclui os dados do código QR e os detalhes do pagamento:

Campos de resposta principais

Resposta de erro

Quando a geração do QR Code falhar, você receberá informações detalhadas sobre o erro:

Etapa 3. Exibir o código QR e processar o pagamento

  1. Exibição de QR Code: Apresente o código QR ao cliente através do canal escolhido.
  2. Leitura do código QR pelo aplicativo do banco: O cliente escaneia o código QR com o aplicativo móvel do banco.
  3. Autorização de pagamento: O cliente confirma o pagamento em seu ambiente bancário.
  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

Os códigos QR Fri são válidos por 5 minutos a partir da sua geração. Se o código QR expirar antes do cliente o digitalizar, você deverá criar uma nova solicitação de pagamento para gerar um novo código.
  • 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”).
  • Apresente instruções de pagamento claras.
  • Exibir um cronômetro de contagem regressiva baseado em qr.expirationDate (Janela de 5 minutos) e notificar o cliente se o QR expirar.

Etapa 4. Acompanhe o status da transação

Acompanhe o progresso do pagamento por QR Code através 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

Verifique se sua integração lida com esses cenários:
  1. Pagamento concluído com sucesso: Leitura do código QR e fluxo de pagamento finalizados.
  2. Expiração de QR Code: Lide com códigos QR 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 pagamentos por QR Code, 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