Tote
InícioIntegraSaiba mais
InícioIntegraSaiba mais
  1. APIs
  • Visão geral
  • O QUE HÁ DE NOVO
    • Release Notes
      • Horizon
  • GUIAS
    • Manuais
      • Diretrizes Básicas
      • Como se autenticar
      • Respostas e status
      • Nossas APIs
      • Webhook
      • FAQ
  • REFERÊNCIA DAS APIS
    • APIs
      • Autenticação
        • Gerar token de acesso
      • Agenda lojista
        • Agenda
          • Cadastrar recebimento em agenda
          • Cadastrar agenda manual
          • Listar agenda por loja
          • Consultar agenda específica
          • Listar transações pelo ID da agenda ou loja
        • Configurações de Agendas
          • Cadastrar configuração
          • Listar configurações da agenda
          • Alterar configuração de uma loja
        • Modalidade
          • Cadastrar modalidades
          • Listar modalidades
          • Listar modalidade por lançamento
          • Alterar tipo de modalidade
        • Lançamentos
          • Listar lançamentos por loja
          • Cadastrar lançamentos
          • Cadastrar lançamento de ajuste
        • Tipo de ajuste
          • Cadastrar um tipo de ajuste
          • Listar tipo de ajuste
      • Acheron
        • Pagamento
          • Cadastrar um pagamento
          • Cancelar um pagamento
          • Criar intenção de pagamento
          • Confirmar intenção de pagamento
          • Cancelar intenção de pagamento
          • Listar intenções de pagamento
          • Criar pagamento via PIX
        • Venda
          • Criar venda com cartão
          • Cancelar venda com cartão
          • Criar venda com portador
          • Cancelar venda com portador
          • Estornar uma venda
        • E-Commerce
          • Criar venda e-commerce
          • Confirmar pagamento e-commerce
          • Listar pagamento e-commerce
          • Cancelar venda e-commerce
          • Gerar token de e-commerce
        • VTEX
          • Criar venda VTEX
          • Confirmar venda VTEX
          • Estornar venda VTEX
          • Cancelar venda VTEX
          • Listar manifesto do provedor de pagamento
        • Simulação
          • Criar simulação
        • Pré-autorização
          • Listar pré-autorização
          • Cancelar valor reservado
          • Listar valor reservado
        • BNPL
          • Confirmar estorno de venda
          • Estornar venda
          • Simular venda
          • Confirmar venda
          • Sensibilizar venda
      • Banking
        • Conciliação bancária
          • Gerar saldo para um emissor
          • Gerar extrato para um emissor
          • Gerar arquivos de conciliação
        • Contas
          • Listar contas digitais
        • Pix
          • Transferir pix
          • Listar status do pix
          • Listar transferências Pix
          • Listar informações de chave
      • Biometria
        • Biometria
        • Handshake fortface
          • Iniciar o processo de autenticação biométrica SDK
          • Iniciar o processo de autenticação biométrica Backoffice
        • Biometria
          • Identificar um rosto
          • Cadastrar uma face utilizando o SDK Fortface
          • Cadastrar uma face através do Backoffice da Fortface
      • Broker
        • Enviar mensagem SMS
      • Cartões
        • Portadores
          • Buscar cartão pelo titular
          • Cadastrar portador adicional
          • Listar cartões do adicional
          • Gerar cartão adicional
        • CVV Virtual
          • Ativar CVV Virtual do titular
          • Inativar CVV Virtual
          • Atualizar data de expiração do CVV
        • Senha
          • Cadastrar senha
          • Alterar senha
          • Autenticar senha do cartão
          • Gerar senha e enviar por SMS
        • Bloqueios e Desbloqueios
          • Bloquear um cartão temporariamente
          • Bloquear permanentemente
          • Listar histórico de bloqueios
          • Listar tipos de bloqueio
          • Desbloquear cartão
        • Cartões
          • Solicitar segunda via
          • Trocar cartão pendente
          • Buscar cartão criptografado
          • Listar histórico de cancelamento
          • Listar tipos de cancelamento
          • Gerar um cartão virtual
          • Listar cartão virtual
          • Buscar cartão pelo id
          • Buscar cartão pelo número
          • Buscar cartão pelo CPF
          • Buscar cartão bandeirado
          • Token Merci
          • Trocar cartão do portador
          • Cadastrar Pessoa Jurídica
          • Solicitar troca do cartão
          • Listar BIN
        • No Name
          • Listar lotes de cartão
          • Criar lote de cartões
          • Destruir cartão
          • Vincular cartão ao titular
          • Vincular cartão adicional
          • Destruir lote de cartões
          • Embossar cartões por lote
          • Listar cartões
        • Vipagem
          • Listar cartões bandeirados
          • Emitir segunda via
      • Embossing
        • Cartões
          • Embossing de cartão
          • Bloquear cartão por falha
          • Listar cartões pendentes
        • Impressoras
          • Inativar impressora
          • Ativar impressora
      • Empréstimo
        • Empréstimo Pix Card
          • Enviar arquivo
          • Alterar dados bancários
          • Transferir via Pix
          • Cadastrar pessoa física
          • Simular empréstimo
          • Confirmar empréstimo
          • Aprovar crédito
          • Criar contrato
          • Consultar pessoa
        • Empréstimo FGTS
          • Simular saldo
          • Obter saldo
          • Cadastrar pessoa física
          • Cadastrar operação
          • Submeter para aprovação
          • Consultar informações
          • Listar produto
          • Consultar pessoa
          • Listar operações
          • Acompanhar operação
          • Listar estado civil
          • Listar bancos
      • Faturamentos
        • Parcelamento de fatura
          • Antecipar uma parcela do parcelamento
          • Antecipar todo o parcelamento
          • Buscar parcelamento pendente
          • Buscar parcelamento ativo
          • Simular antecipação
          • Parcelar faturas
        • Ciclos de fatura
          • Consultar ciclos de vencimento
          • Alterar o ciclo de vencimento
        • Consulta de faturas
          • Consultar lançamentos futuros
          • Consultar faturas por período
          • Consultar faturas futuras
          • Consultar última fatura fechada
          • Consultar fatura detalhada
          • Consultar fatura atual
          • Visualizar saldo detalhado
        • Faturas digitais
          • Receber fatura em PDF
          • Aderir à fatura digital
          • Cancelar fatura digital
          • Aderir à fatura por SMS
          • Cancelar fatura por SMS
      • Financiamentos
        • Parcelamento total
          • Simular parcelamento devedor total
        • Parcelamento manual
          • Simular parcelamento manual
      • Gestão de contas
        • Cadastrar cartão físico para titular
      • Lançamentos
        • Ajustes
          • Lançar um ajuste financeiro
          • Listar um ajuste financeiro
          • Lançar ajustes a débito
          • Lançar ajustes a crédito
          • Listar tipos de ajustes
          • Listar faturas ajustadas
          • Lançar um ajuste na fatura
        • Vendas
          • Antecipar venda total
          • Antecipar venda avulsa
        • Pagamentos
        • Antecipação
          • Listar compras passíveis de antecipação
        • Baixas bancárias
          • Estornar lançamento de baixa bancária
          • Lançar baixa báncaria
          • Lançar baixa bancária de pagamento
          • Estornar pagamento de baixa bancária
      • Loja
        • Formas de Pagamentos
          • Listar formas de pagamento
          • Cadastrar forma de pagamento
          • Atualizar forma de pagamento
          • Consultar parcelas de uma loja
        • Tarifas
          • Listar tarifas
          • Cadastrar tarifa
          • Associar tarifa a uma loja
          • Cancelar tarifas com a loja
          • Listar tarifas por loja
          • Consultar uma tarifa
          • Alterar cadastro de uma tarifa
        • Lojas
          • Cadastrar uma loja
          • Consultar uma loja
          • Consultar loja por id externo
          • Listar loja pelo CNPJ
          • Listar lojas
          • Alterar uma loja
      • Pacote SMS
        • Contratar um pacote SMS
        • Cancelar um pacote SMS
        • Consultar pacotes do portador
        • Habilitar celular para adesão do pacote
        • Habilitar celular para receber bônus
        • Consultar pacotes disponíveis
        • Consultar pacotes contratados
      • Parâmetros
        • Listar parâmetros cadastrados
        • Listar parâmetros exibíveis
      • Pix
        • Pix Imediato
          • Listar chaves Pix Imediato
          • Gerar Pix Imediato
          • Listar uma chave Pix Imediato
      • Pix Card
        • PixCard
          • Transferir via Pix
          • Consultar CPF
          • Cadastrar cliente
          • Simular operação
          • Confirmar operação
          • Cadastrar documento do portador
        • Assinatura
          • Listar as assinaturas
          • Cadastrar assinatura
          • Verificar assinaturas para cobrança
          • Listar assinaturas válidas
          • Listar planos
          • Alterar assinatura pelo CPF
        • Conta Digital
          • Listar termos obrigatórios
          • Cadastrar termo obrigatório
          • Cadastrar documento do portador
          • Criar uma conta digital
          • Criar uma conta alias
          • Listar contas pelo identificador
          • Listar informações do portador
        • Transferência
          • Agendar transferência
          • Efetuar transferência
          • Listar status de transferência
          • Listar devoluções
          • Listar transferências
          • Listar agendamentos de transferências
        • Relatórios
          • Listar operações
          • Listar relatórios de assinaturas
          • Listar adesões
        • QR Code
          • Criar QR Code estático
          • Decodificar QR Code
        • Chaves
          • Confirmar reivindicações
          • Fazer reivindicação
          • Cadastrar chave
          • Deletar chave
          • Listar chaves
          • Consultar chaves pelo identificador
          • Listar reivindicações
        • Limites
          • Criar limite de horário
          • Associar conta a grupo de serviço
          • Listar destinos confiáveis
          • Alterar limite do destino confiável
          • Listar limites de horários
          • Listar requisições
          • Remover destino confiável
      • Portadores
        • Gestão de portadores
          • Listar status do portador pelo CPF
          • Listar portadores
          • Alterar dados do portador
          • Alterar status de ativo problemático
          • Listar informações do portador
          • Alterar o limite do portador
          • Bloquear um portador
          • Desbloquear um portador
          • Listar adicionais pelo CPF
          • Listar portadores em lote
          • Listar contas pelo CPF (simplificado)
          • Listar contas pelo CNPJ
          • Alterar produto do portador
          • Listar contas pelo documento
          • Listar contas pelo RG
          • Listar contas pelo nome
          • Alterar vipagem
          • Consultar ciclo do portador
          • Listar contas pelo CPF (completo)
        • Gestão de dependentes
          • Listar dependentes pelo titular
          • Cadastrar dependentes
        • Gestão de telefones
          • Listar telefones
          • Cadastrar telefone
          • Deletar telefone
          • Receber SMS
        • Visualização de histórico
          • Listar histórico do portador
          • Listar ocorrências
          • Listar inadimplências pelo portador
          • Listar o histórico de limites
        • Gestão de senhas
          • Enviar senha por SMS
          • Alterar senha do portador
        • Cadastro de contas
          • Cadastrar uma conta PJ
          • Cadastrar uma conta PF
        • Informações da base de dados
          • Listar tipos de bloqueio
          • Listar escolaridades
          • Listar ocupações
        • BNPL
          • Consultar informações do portador
      • Portuno
        • Conta
          • Listar conta
          • Criar uma conta
          • Trocar o segredo da conta
        • Integração
          • Listar integrações
          • Alterar tempo de expiração de uma integração
      • Produtos
        • Produtos
          • Consultar produtos
          • Consultar um produto
        • Serviços financeiros
          • Listar serviços financeiros
      • Regulatório
        • Listar informações
      • Recompensa
        • Aderir à anuidade bonificada
        • Cancelar anuidade bonificada
        • Listar anuidades do produto
        • Listar anuidade do portador
        • Listar anuidades
        • Listar as anuidades
        • Cadastrar anuidades
      • Serviços Bancários
        • Registrar um boleto online
        • Listar pagamentos
        • Listar boleto completo
        • Listar contas habilitadas
      • Seguros
        • Seguros
          • Cancelar adesão do titular
          • Aderir seguro para o titular
          • Aderir seguro para dependente
          • Cancelar adesão do dependente
          • Listar seguros de dependentes
          • Listar seguros disponíveis
          • Cancelar um seguro
          • Listar seguros do portador
          • Listar campos de adesão ao seguro
          • Listar campos de adesão do portador
          • Listar seguros cancelados
        • Bilhetes de Seguro
          • Listar bilhetes de um portador
          • Listar o modelo de operação
          • Listar um bilhete de adesão
        • Cobranças e Pagamentos
          • Fazer estímulo de cobrança
        • Termos da Adesão
          • Listar termos de adesão
          • Listar modelos do código de operação
          • Listar termos de um seguro
      • SMS Notice
        • Processamento
          • Listar os eventos
          • Criar um evento
          • Alterar um evento
          • Listar as variáveis
          • Criar variáveis
          • Listar as transações
          • Criar mensagem para fila
        • Serviços
          • Criar um serviço de SMS
          • Listar serviços cadastrados
          • Alterar um serviço de SMS
          • Listar um serviço específico
        • Pacote de SMS
          • Listar os pacotes de sms
          • Cadastrar pacote SMS
          • Listar um pacote específico
          • Alterar um pacote específico
          • Aderir a um pacote SMS
          • Cancelar uma adesão
          • Listar adesões de um portador
          • Alterar o telefone do pacote
  1. APIs

Portuno

Aplicação de autenticação que implementa autenticação multifator (MFA) com geração de senhas de uso único e temporárias (OTP). Ele garante a autenticidade de transações através de tokens criptografados com segredos compartilhados.

Fluxo de autorização#

Portuno autorização
Figura 1. Fluxo de autorização

1. Entrada de Dados no Terminal#

O portador insere o CPF e o Token no Terminal de Pagamento (POS/Pinpad).

2. Envio de Dados para o PDV/TEF#

O terminal encaminha o CPF e o Token para o PDV/TEF.
O PDV/TEF monta uma transação com os dados do portador e envia para a Processadora de Pagamentos.

3. Validação do Token no Portuno#

A Processadora encaminha o CPF e o Token para o Portuno.
O Portuno valida a autenticidade do Token:
Se o Token for válido: O Portuno retorna uma aprovação para a Processadora.
Se o Token for inválido: O Portuno retorna uma negação com o erro Token Inválido.

4. Encaminhamento para Autorização#

Em caso de aprovação do Token:
A Processadora envia a transação para autorização junto à bandeira ou ao emissor.
Em caso de negação do Token:
A transação é rejeitada pelo PDV com a mensagem de erro apropriada.

5. Resultado da Transação#

Aprovada: A transação segue para conclusão no terminal.
Negada: O terminal exibe uma mensagem indicando que a transação foi recusada devido a um Token Inválido.

Fluxo entre o APP e o Portuno#

jornada app
Figura 2. Fluxo do APP com Portuno
O fluxo de autenticação segue as etapas mostradas na imagem acima e descritas abaixo:

1. APP faz autenticação no Horizon#

O APP solicita a autenticação e recebe o token JWT.

2. Consulta Cartões do Portador#

O APP consulta os cartões do portador via Horizon e recebe os dados dos cartões.

3. Verificação do Secret no Portuno#

O Portuno consulta se o CPF e o produto (Emissor + ID) já têm um secret cadastrado.

Se o secret existir:#

O token é gerado com base nesse secret, e o fluxo transacional segue via API/PDV.

Se o secret não existir:#

O Portuno cadastra a conta e recebe um novo secret.
O token é gerado a partir do novo secret, e o fluxo transacional segue.

Jornada de Autenticação#

1.
O portador realiza uma transação em uma aplicação (ex: APP) protegida pelo Portuno.
2.
O APP solicita ao Code Generator (CG) a criação ou atualização de uma conta, recebendo um secret.
3.
O APP gera um token criptografado usando o secret compartilhado.
4.
A transação é enviada ao autorizador (ex: RPE), que encaminha a solicitação de confirmação ao Portuno, contendo o identificador da conta e o token gerado.
5.
O Portuno decriptografa o token, valida se o secret é correto e autoriza ou nega a transação.
6.
O resultado da autorização é retornado ao APP, que informa o portador sobre o sucesso ou falha da transação.
O Code Generator (CG) é o componente responsável por solicitar o cadastro de contas, criar e atualizar os secrets dessas contas. Além disso, ele gera tokens de autorização usados no processo de autenticação multifator (MFA).
Para garantir uma verificação correta, a configuração do TOTP deve ser idêntica tanto no Portuno quanto no CG. Isso inclui parâmetros como o número de caracteres do código e o tempo de expiração, assegurando que ambos os sistemas estejam sincronizados e a autenticação funcione corretamente.

Endpoints#

Integração#

TipoEndpointDescrição
GET/api/v1/portuno/integrationsLista as integrações cadastradas

Conta#

TipoEndpointDescrição
POST/api/v1/portuno/accountsCadastra uma conta
PUT/api/v1/portuno/accountsTroca o secret de uma conta
GET/api/v1/portuno/accountsLista as contas

Casos de uso#

A seguir, detalhamos os principais casos de uso na Jornada de lançamentos, explicando como cada operação é realizada através das API.
Criar uma conta
Use este endpoint para criar uma conta Portuno.
Exemplo de request body :
{
  
  "integration": "Teste",
  "externalId": "velho",
  "issuer": "Sandbox"

 
}'
Exemplo de response:

 {
  
    id": 12,
    "externalId": "velho",
    "secret": "X5OWXEE3TNCKV4WA",
    "qrUri": "otpauth://totp/Teste%3Avelho?secret=X5OWXEE3TNCKV4WA&issuer=Teste&algorithm=SHA1&digits=6&period=30",
    "status": "ACTIVE",
    "createdAt": "2025-01-21"
 }
Listar contas
Use este endpoint para listar as contas já cadastradas.
Exemplo de Query Parameters :
Utilize os seguintes query parameters externalId: "TESTE", issuer: "Sandbox" productId: "1" para listar as contas.
Exemplo de response:
[
    {
        "id": 2,
        "externalId": "TESTE",
        "secret": "S2KHY4LMMLVJFWK5",
        "qrUri": "otpauth://totp/Teste%3ATESTE?secret=S2KHY4LMMLVJFWK5&issuer=Teste&algorithm=SHA1&digits=6&period=30",
        "status": "ACTIVE",
        "createdAt": "2024-08-14"
    }
]
Trocar o segredo da conta
Use este endpoint para trocar o segredo de uma conta já cadastrada.
Exemplo de request body :
{
  
  "integration": "Teste",
  "externalId": "Novo",
  "issuer": "Sandbox"

 
}
Exemplo de response:
{
    "id": 2,
    "externalId": "TESTE",
    "secret": "TU2QF4BCBQBGFNV5",
    "qrUri": "otpauth://totp/Teste%3ATESTE?secret=TU2QF4BCBQBGFNV5&issuer=Teste&algorithm=SHA1&digits=6&period=30",
    "status": "ACTIVE",
    "createdAt": "2025-01-21"
}
Listar integrações
Use este endpoint para listar integrações já cadastradas.
Exemplo de Query Parameters :
Utilize o seguinte query parameters nomeEmissor: "Sandbox" para listar todas as integrações com esse emissor.
Exemplo de response:
[
    {
        "id": 2,
        "description": "Teste",
        "integration": "Teste",
        "issuer": "Sandbox",
        "active": true,
        "productId": 1,
        "token": {
            "digits": 6,
            "period": 30
        }
    },
    {
        "id": 3,
        "description": "Descricao",
        "integration": "Integracao",
        "issuer": "Sandbox",
        "active": true,
        "productId": 2,
        "token": {
            "digits": 6,
            "period": 30
        }
    },
    {
        "id": 4,
        "description": "NewDescricao",
        "integration": "NewIntegracao",
        "issuer": "Sandbox",
        "active": true,
        "productId": 2,
        "token": {
            "digits": 6,
            "period": 30
        }
    },
    {
        "id": 5,
        "description": "NewDescricao",
        "integration": "NovoIntegracao",
        "issuer": "Sandbox",
        "active": true,
        "productId": 2,
        "token": {
            "digits": 6,
            "period": 30
        }
    },
    {
        "id": 6,
        "description": "NewDescricao",
        "integration": "Novo",
        "issuer": "Sandbox",
        "active": true,
        "productId": 2,
        "token": {
            "digits": 6,
            "period": 30
        }
    },
    {
        "id": 1,
        "description": "Integration Sandbox",
        "integration": "Integration Sandbox",
        "issuer": "Sandbox",
        "active": true,
        "productId": 1,
        "token": {
            "digits": 6,
            "period": 30
        }
    },
    {
        "id": 7,
        "description": "n",
        "integration": "I",
        "issuer": "Sandbox",
        "active": true,
        "productId": 2,
        "token": {
            "digits": 6,
            "period": 20
        }
    },
    {
        "id": 8,
        "description": "NewDescricao",
        "integration": "teste",
        "issuer": "Sandbox",
        "active": true,
        "productId": 2,
        "token": {
            "digits": 6,
            "period": 30
        }
    }
]
Os endpoints irão retornar os dados que podem ser acessados de acordo com suas credenciais de autenticação. Para mais informações, visite a página de autenticação.

Serviços relacionados#

API Portuno

Materiais relacionados#

Como testar endpoints através do Tote
Diretrizes básicas do Horizon
Respostas e possíveis erros
Página anterior
Consultar informações do portador
Próxima página
Listar conta