Pagamento PIX

O fluxo de pagamento PIX depende da chamada de múltiplos serviços da API, sendo arquitetado para funcionar da seguinte forma:

  1. Mediante requisição à API, o código para pagamento é criado, e um endereço para conexão a um hub SignalR é informado no retorno.
  2. O cliente se conecta ao hub SignalR para aguardar a notificação de que o pagamento foi efetuado.
  3. Com o pagamento confirmado, deve ser realizada uma nova requisição à API para confirmar o pagamento de fato e integrar as informações de baixa ao sistema.

Hub SignalR

O SignalR é uma biblioteca que simplifica a adição de funcionalidades Web em tempo real em aplicações, facilitando a comunicação entre o servidor e o cliente. No caso do pagamento PIX, o hub SignalR é utilizado para notificar o cliente de que o pagamento foi efetuado. Após a criação da transação PIX, o cliente pode se conectar ao hub SignalR para receber a notificação de pagamento confirmado.

Esta documentação procura detalhar o funcionamento do hub de notificação de pagamento, descrevendo como deve ser acessado e por quais eventos a notificação de pagamento será informada. Para mais informações, consulte a documentação do SignalR.

Comunicação com o hub SignalR

O hub SignalR é acessado através da rota /instantpix/pixhub no endereço base do servidor Pay. Ao conectar, a URL deve conter um parâmetro pixCodeId com o identificador do código PIX para o qual o cliente deseja ser notificado. A resposta da requisição de criação da transação PIX já informa o endereço do hub para conexão contendo o parâmetro.

Quando um cliente se conecta ao hub, passa a fazer parte de um grupo contendo todos os clientes registrados para o mesmo pixCodeId. Quando o pagamento for confirmado, todos os clientes registrados no grupo receberão a notificação de pagamento.

O hub não possui política de reconexão automática, sendo necessário implementar explicitamente um tratamento de erro para reconectar em caso de falha.

O hub irá enviar um sinal de keep-alive em intervalos de 15 segundos para confirmar que a conexão com o cliente esteja ativa. Caso não receba resposta, será observado um período de timeout de 30 segundos, e então o cliente será desconectado.

Eventos

Devem ser implementados handlers para os seguintes eventos:

  • Paid()
    • Notifica o cliente de que o pagamento foi efetuado. Sem parâmetros.

Métodos

Os seguintes métodos estão disponíveis para chamada no hub de pagamento PIX:

  • NotifyIfPaymentConfirmed()
    • Verifica se o pagamento foi confirmado para o código PIX da conexão. Caso tenha sido confirmado, dispara o evento Paid() para todos os clientes vinculados ao código PIX. Sem parâmetros.
    • A notificação Paid() já é disparada automaticamente quando o pagamento for confirmado. Dessa forma, o método NotifyIfPaymentConfirmed() pode ser utilizado como forma de consultar ativamente o status de pagamento do código.

Boas práticas

  • Implemente um tratamento de erro para reconectar ao hub em caso de falha.
    • Evite a sobrecarga de requisições ao hub. Se a conexão falhar repetidamente, implemente lógica para não sobrecarregar o servidor.
    • Ajuste os parâmetros KeepAliveInterval e ServerTimeout da conexão para refinar o gerenciamento de reconexão no cliente.
    • É possível monitorar o estado da conexão com o hub através de eventos disponíveis para o cliente SignalR. Consulte documentação específica da linguagem utilizada no desenvolvimento para verificar quais os eventos disponíveis.
  • Mantenha registros de todas as interações durante a comunicação com o hub para facilitar a identificação de eventuais problemas.
  • Evite chamadas síncronas ao hub, pois isso pode bloquear a execução no cliente.
  • Remova handlers de eventos antes de registrar novos handlers para evitar múltiplas execuções.

Exemplo de implementação do cliente (C#)

internal class Program
{
    private static async Task Main(string[] args)
    {
        // URL do hub SignalR
        string hubUrl = "http://{endereço base do Hub}/instantpix/pixhub?pixCodeId=1000";

        // Cria a conexão com o hub
        var connection = new HubConnectionBuilder()
            .WithAutomaticReconnect()
            .WithUrl(hubUrl)
            .WithKeepAliveInterval(TimeSpan.FromSeconds(15))
            .WithServerTimeout(TimeSpan.FromSeconds(60))
            .Build();

        //Evento para capturar erros durante a comunicação
        connection.Closed += async (error) =>
        {
            Console.WriteLine("Conexão fechada: " + error?.Message);

            await Task.Delay(5000); // Espera 5 segundos antes de tentar reconectar
            await connection.StartAsync(); // Tenta reconectar
        };

        // Remove handlers do evento "Paid" caso já existam
        connection.Remove("Paid");

        // Configura o hadler do evento "Paid"
        connection.On("Paid", () =>
        {
            Console.WriteLine("Evento 'Paid' recebido: Pagamento confirmado!");
        });

        // Inicia a conexão
        try
        {
            await connection.StartAsync();
            Console.WriteLine("Conectado ao hub SignalR!");

            // Chama o método NotifyIfPaymentConfirmed
            await connection.InvokeAsync("NotifyIfPaymentConfirmed");
            Console.WriteLine("Método 'NotifyIfPaymentConfirmed' chamado com sucesso.");
        }
        catch (Exception ex)
        {
            Console.WriteLine("Erro ao conectar ao hub SignalR: " + ex.Message);
            return;
        }

        // Mantém o cliente em execução para receber eventos
        Console.WriteLine("Pressione Enter para sair...");
        Console.ReadLine();

        // Fecha a conexão
        await connection.StopAsync();
        Console.WriteLine("Conexão encerrada.");
    }
}

Cancelamento da transação

Uma requisição de cancelamento pode ser realizada à API informando o identificador da transação a ser cancelada. O cancelamento pode ser realizado a qualquer momento anterior à confirmação do pagamento.

Caso a transação seja abandonada ou o pagamento não seja confirmado por chamada à API, a transação será cancelada automaticamente após um período de tempo configurável no serviço MultiVendas do ambiente (padrão de 30 minutos).

Caso o pagamento do código seja efetuado mas a aplicação não informe a confirmação por meio da API, um subsequente cancelamento (manual ou automático) agendará também o reembolso do valor ao pagador.

Após a integração do pagamento, o cancelamento pela API não será mais possível, e o estorno do movimento deverá ser feito diretamente no sistema.