Fluxo de Pagamento PIX


Documentação completa para implementação de pagamentos via PIX na API Extratta. Este guia explica como configurar e processar pagamentos PIX de forma automática para proprietários de veículos.


Visão Geral

O pagamento via PIX na Extratta permite que empresas realizem transferências instantâneas para proprietários de veículos de forma automática durante a criação de viagens. O sistema detecta automaticamente quando usar PIX e processa o pagamento em tempo real.

Pré-requisitos

Requisitos Obrigatórios

  • Proprietário deve ter chave PIX cadastrada no sistema
  • Empresa deve ter saldo suficiente para o pagamento
  • Configurar evento com HabilitarPagamentoCartao = false
  • Informar os campos NomeUsuarioAudit e DocumentoUsuarioAudit para auditoria

Informações Necessárias

  • CPF/CNPJ do proprietário
  • Chave PIX válida (CPF e CNPJ)
  • Valor do pagamento
  • Dados da viagem completos

Cadastro de Chave PIX

Para que um proprietário possa receber pagamentos via PIX, é necessário cadastrar uma chave PIX válida no sistema.

Endpoint: POST /Pix/CadastrarChaveProprietario

Tipos de Chave Suportados

Tipo Código Descrição Formato Exemplo
CPF 0 Documento CPF 11 dígitos "12345678901"
CNPJ 1 Documento CNPJ 14 dígitos "12345678000195"
E-mail 3 Endereço de e-mail email@dominio.com "motorista@exemplo.com"
Telefone 2 Celular com DDD 11 dígitos "11987654321"
Chave Aleatória 4 Chave aleatória do proprietário 36 caracteres e2823bff-1f41-4499-8ad2-94033be0ada5
Agência e Conta 5 Dados bancários do proprietário Agência, conta com dígito e código do banco Agência: "12548" / Conta: "65842" / Banco: "001"

Exemplo 1: Cadastro com CPF

Request:

{
  "CNPJAplicacao": "12345678000195",
  "Token": "seu-token-de-autenticacao",
  "CPFCNPJProprietario": "12345678901",
  "Chave": "12345678901",
  "Tipo": 0,
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Sistema Integração"
}

Exemplo 2: Cadastro com E-mail

Request:

{
  "CNPJAplicacao": "12345678000195",
  "Token": "seu-token-de-autenticacao",
  "CPFCNPJProprietario": "12345678901",
  "Chave": "motorista@exemplo.com",
  "Tipo": 3,
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Sistema Integração"
}

Exemplo 3: Cadastro com Telefone

Request:

{
  "CNPJAplicacao": "12345678000195",
  "Token": "seu-token-de-autenticacao",
  "CPFCNPJProprietario": "12345678901",
  "Chave": "11987654321",
  "Tipo": 2,
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Sistema Integração"
}

Exemplo 4: Cadastro com Chave Aleatória

Request:

{
  "CNPJAplicacao": "12345678000195",
  "Token": "seu-token-de-autenticacao",
  "CPFCNPJProprietario": "12345678901",
  "Chave": "",
  "Tipo": 4,
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Sistema Integração"
}

Exemplo 5: Cadastro com Agência e Conta

Para cadastrar o proprietário utilizando dados bancários, informe o campo Tipo com o valor 5. Nesse cenário, o campo Chave deve ser enviado como null, e os campos Agencia, Conta e CodBanco são obrigatórios.

No campo Conta, o dígito verificador deve ser enviado junto ao número da conta, sem separação por espaço ou hífen.

Request:

{
  "CNPJAplicacao": "12345678000195",
  "Token": "seu-token-de-autenticacao",
  "CPFCNPJProprietario": "12345678901",
  "Chave": null,
  "Tipo": 5,
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Sistema Integração",
  "Agencia": "12548",
  "Conta": "65842",
  "CodBanco": "001"
}

Resposta de Sucesso

{
  "Sucesso": true,
  "Mensagem": "Chave PIX cadastrada com sucesso",
  "Objeto": {
    "ChavePix": "12345678901",
    "Tipo": 0,
    "Status": "Ativa"
  }
}

Validações do Sistema

Quando você cadastra uma chave PIX, o sistema executa validações em diferentes níveis para garantir a segurança:

Validação de Formato (Automática)

O sistema valida automaticamente o formato da chave antes de criar a solicitação:

  • CPF: Deve ter exatamente 11 dígitos numéricos (apenas números, sem pontos ou hífens)
  • CNPJ: Deve ter exatamente 14 dígitos numéricos (apenas números, sem pontos, barras ou hífens)
  • E-mail: Deve conter "@" e "." (validação básica de formato)
  • Telefone: Deve ter exatamente 11 dígitos numéricos (DDD + número, apenas números)
  • Chave Aleatória (EVP): Deve ter exatamente 36 caracteres incluindo os hífens (formato UUID)
  • Agência e Conta: Quando o Tipo for 5, os campos Agencia, Conta e CodBanco devem ser enviados obrigatoriamente. A conta deve conter o dígito verificador junto, sem espaço e sem hífen.

Validação DICT (Banco Central)

A validação DICT é executada ao realizar a chamada do método de cadastro da chave pix:

  • Propriedade da Chave: Verifica se a chave PIX realmente pertence ao CPF/CNPJ informado
  • Status da Chave: Confirma se a chave está ativa no sistema bancário
  • Dados Bancários: Valida se a conta de destino está funcionando
  • Titularidade: Confirma se o proprietário é o titular da chave PIX

Exemplo de Erro - Chave não pertence ao CPF

{
  "Sucesso": false,
  "Mensagem": "Chave PIX não pertence ao CPF informado",
  "Faults": [
    {
      "Type": 1,
      "Code": "PIX007",
      "Message": "Validação DICT: Chave PIX 12345678901 não está vinculada ao CPF 98765432100"
    }
  ]
}

Outros Possíveis Erros

Chave já cadastrada

{
  "Sucesso": false,
  "Mensagem": "Chave PIX já cadastrada para outro proprietário",
  "Faults": [
    {
      "Type": 1,
      "Code": "PIX001",
      "Message": "Chave PIX já existe no sistema"
    }
  ]
}

Formato inválido

{
  "Sucesso": false,
  "Mensagem": "Chave de tipo CPF com formato inválido. Deve ter 11 caracteres numéricos.",
  "Faults": [
    {
      "Type": 1,
      "Code": "PIX006",
      "Message": "Chave de tipo CPF com formato inválido. Deve ter 11 caracteres numéricos."
    }
  ]
}

Chave inativa no Banco Central

{
  "Sucesso": false,
  "Mensagem": "Chave PIX inativa ou inexistente",
  "Faults": [
    {
      "Type": 1,
      "Code": "PIX008",
      "Message": "Chave PIX não encontrada no DICT do Banco Central"
    }
  ]
}

Validação N1 - Gestor Nível 1

Após a validação da DICT e do formato de chave, a solicitação fica "Pendente Nível 1" e deve ser aprovada por um Gestor Nível 1 no portal:

  • Análise Manual: Gestor verifica se os dados estão corretos
  • Aprovação/Rejeição: Gestor pode aprovar ou rejeitar a solicitação

Validação N2 - Gestor Nível 2 (Opcional)

Se a empresa tiver configurado Gestor Nível 2, a solicitação aprovada pelo N1 fica "Pendente Nível 2":

  • Segunda Análise: Gestor Nível 2 faz uma segunda verificação
  • Aprovação Final: Apenas após aprovação do N2 a chave é efetivamente cadastrada

Fluxo Completo de Cadastro

Fluxo de Aprovação por Gestores

  1. Solicitação: Cliente envia chave PIX via API
  2. Validação de Formato: Sistema valida formato automaticamente
  3. Validação DICT: Sistema consulta Banco Central
  4. Criação da Solicitação: Status fica "Pendente Nível 1"
  5. Notificação: Gestores Nível 1 recebem e-mail
  6. Aprovação N1: Gestor Nível 1 aprova no portal
  7. Status Atualizado:
    • Se empresa tem N2: Status fica "Pendente Nível 2"
    • Se empresa não tem N2: Status fica "Aprovada"
  8. Aprovação N2 (se aplicável): Gestor Nível 2 aprova no portal
  9. Chave Cadastrada: Proprietário habilitado para receber PIX

Para cadastro com Tipo = 5, a habilitação do proprietário ocorre usando os dados de agência, conta e banco informados no endpoint /Pix/CadastrarChaveProprietario. Após aprovação, o proprietário também fica apto para receber pagamentos via PIX no fluxo de viagem.

Status das Solicitações

Status Código Descrição Próxima Ação
Pendente Nível 1 1 Aguardando aprovação do Gestor N1 Gestor N1 deve aprovar/rejeitar
Pendente Nível 2 2 Aguardando aprovação do Gestor N2 Gestor N2 deve aprovar/rejeitar
Aprovada 3 Chave cadastrada com sucesso Proprietário pode receber PIX
Recusada 4 Solicitação rejeitada Cadastrar nova solicitação

Configuração de Gestores

Para que o sistema funcione, a empresa deve ter gestores configurados:

  • Gestor Nível 1: Obrigatório para todas as empresas
  • Gestor Nível 2: Opcional, para empresas que querem dupla validação

Configuração: Os gestores são configurados mediante contato do cliente com o time Extratta.

Configuração de Viagem com PIX

Para que o pagamento seja processado via PIX automaticamente, configure o evento da viagem seguindo as regras abaixo.

Regras para PIX Automático

Configurações Obrigatórias:

  • HabilitarPagamentoCartao = false
  • Proprietário deve ter chave PIX cadastrada e aprovada
  • Valor deve ser maior que zero
  • Status deve ser Aberto (0) ou Baixado (2)
  • Para proprietário cadastrado com Tipo = 5, os dados Agencia, Conta e CodBanco devem estar cadastrados e aprovados no cadastro PIX do proprietário

Configurações que IMPEDEM PIX:

  • HabilitarPagamentoCartao = true
  • Proprietário sem chave PIX cadastrada ou aprovada
  • Proprietário com Tipo = 5 sem agência, conta ou código do banco cadastrados e aprovados
  • Status diferente de Aberto ou Baixado

Detecção Automática

O sistema detecta automaticamente quando usar PIX baseado nas seguintes condições: - NÃO é pagamento por cartão (HabilitarPagamentoCartao = false) - E proprietário tem chave PIX cadastrada

Agência e Conta no Fluxo de Pagamento

Quando o proprietário estiver cadastrado com Tipo = 5, o fluxo de pagamento PIX permanece o mesmo para a integração da viagem. Não é necessário enviar Agencia, Conta ou CodBanco no payload de /Viagem/Integrar ou /ViagemV2/Integrar.

Esses dados devem ser enviados previamente no cadastro da chave PIX do proprietário pelo endpoint /Pix/CadastrarChaveProprietario. Durante o processamento do pagamento, o sistema utiliza automaticamente a agência, a conta e o código do banco já cadastrados e aprovados para o proprietário.

Campos obrigatórios para o cadastro com Tipo = 5:

Campo Obrigatório Descrição
Agencia Sim Agência da conta do proprietário.
Conta Sim Conta do proprietário com o dígito verificador junto, sem espaço e sem hífen.
CodBanco Sim Código do banco da conta do proprietário.

Exemplo de cadastro utilizado pelo fluxo de pagamento:

{
  "CNPJAplicacao": "12345678000195",
  "Token": "seu-token-de-autenticacao",
  "CPFCNPJProprietario": "12345678901",
  "Chave": null,
  "Tipo": 5,
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Sistema Integração",
  "Agencia": "12548",
  "Conta": "65842",
  "CodBanco": "001"
}

Exemplo: Integração V1 com PIX

Endpoint: POST /Viagem/Integrar

Request:

{
  "Token": "seu-token-de-autenticacao",
  "CNPJAplicacao": "12345678000195",
  "CNPJEmpresa": "98765432000198",
  "CPFCNPJProprietario": "12345678901",
  "CPFMotorista": "12345678901",
  "Placa": "ABC1234",
  "NumeroControle": "VIAGEM001",
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Sistema Integração",
  "ViagemEventos": [
    {
      "TipoEvento": 0,
      "ValorPagamento": 800.00,
      "Status": 2,
      "HabilitarPagamentoCartao": false,
      "NumeroControle": "ADT001",
      "Instrucao": "Adiantamento via PIX"
    },
    {
      "TipoEvento": 1,
      "ValorPagamento": 1500.00,
      "Status": 2,
      "HabilitarPagamentoCartao": false,
      "NumeroControle": "SLD001",
      "Instrucao": "Saldo via PIX"
    }
  ]
}

Exemplo: Integração V2 com PIX

Endpoint: POST /ViagemV2/Integrar

Request:

{
  "Token": "seu-token-de-autenticacao",
  "CnpjAplicacao": "12345678000195",
  "CNPJEmpresa": "98765432000198",
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Sistema Integração",
  "DadosViagem": {
    "DadosIniciais": {
      "NumeroControle": "VIAGEM001"
    },
    "Documentos": {
      "MotoristaDocumento": "12345678901",
      "ProprietarioDocumento": "12345678901"
    },
    "Veiculo": {
      "Placa": "ABC1234"
    },
    "ViagemEventos": [
      {
        "TipoEvento": 1,
        "ValorPagamento": 1500.00,
        "Status": 2,
        "HabilitarPagamentoCartao": false,
        "NumeroControle": "SLD001",
        "Instrucao": "Pagamento de frete via PIX"
      }
    ]
  }
}

Para pagamentos de proprietários cadastrados com Tipo = 5, os exemplos de integração da viagem permanecem iguais. A agência, a conta e o código do banco não são enviados no evento da viagem; o sistema busca essas informações no cadastro PIX aprovado do proprietário.

Processamento Automático do PIX

Quando você envia uma viagem com as configurações corretas, o sistema processa o PIX automaticamente em tempo real.

Fluxo de Processamento

  1. Validação Inicial
  2. Verifica se proprietário tem chave PIX cadastrada
  3. Para cadastro com Tipo = 5, verifica se agência, conta e código do banco estão cadastrados e aprovados

  4. Valida se há saldo suficiente na conta

  5. Verificação de Limites

  6. Limite por transação (Ex: R$ 5.000,00)
  7. Limite diário acumulado (Ex: R$ 20.000,00)

  8. Se exceder → Evento vai para aprovação manual

  9. Execução do PIX

  10. Sistema cria transação PIX automaticamente
  11. Quando o cadastro do proprietário for Tipo = 5, utiliza os dados bancários cadastrados previamente para direcionar o pagamento
  12. Envia comando para o Banco Central

  13. PIX é processado em tempo real (máximo 10 segundos)

  14. Confirmação

  15. Evento fica com status "Baixado"
  16. Data/hora do pagamento é registrada
  17. Comprovante é gerado automaticamente

Respostas da API

Resposta de Sucesso

Quando o PIX é processado com sucesso, você recebe:

{
  "Sucesso": true,
  "Mensagem": "Viagem integrada com sucesso",
  "Objeto": {
    "IdViagem": 12345,
    "NumeroDocumento": "DOC123456",
    "Eventos": [
      {
        "IdViagemEvento": 67890,
        "NumeroControle": "SLD001",
        "Token": "evento-token-abc123",
        "TipoEventoViagem": 1,
        "Status": 2,
        "DataHoraPagamento": "2024-01-15T10:30:00",
        "OperacaoCartao": {
          "Status": 1,
          "Mensagem": "PIX processado com sucesso",
          "TipoOperacao": "PIX",
          "ValorProcessado": 1500.00,
          "DataProcessamento": "2024-01-15T10:30:00",
          "EndToEndId": "E12345678202401151030123456789"
        }
      }
    ]
  }
}

Possíveis Erros

Erro: Dados bancários não cadastrados para Tipo 5

{
  "Sucesso": false,
  "Mensagem": "Proprietário não possui agência, conta ou código do banco cadastrados para pagamento PIX",
  "Faults": [
    {
      "Type": 1,
      "Code": "PIX009",
      "Message": "Cadastro PIX do proprietário com Tipo 5 incompleto ou não aprovado"
    }
  ]
}

Erro 1: Proprietário sem chave PIX

{
  "Sucesso": false,
  "Mensagem": "Proprietário não possui chave PIX cadastrada",
  "Faults": [
    {
      "Type": 1,
      "Code": "PIX002",
      "Message": "Proprietário sem permissão para receber pagamentos Pix pela empresa"
    }
  ]
}

Erro 2: Limite excedido

{
  "Sucesso": false,
  "Mensagem": "Valor excede o limite unitário de R$ 5.000,00. Parcela foi bloqueada e enviada para aprovação do gestor.",
  "Objeto": {
    "IdViagem": 12345,
    "Eventos": [
      {
        "IdViagemEvento": 67890,
        "Status": 1,
        "MotivoBloqueio": "Valor excede o limite unitário de R$ 5.000,00"
      }
    ]
  }
}