Bem-vindo ao Banking as a Service do Itaú!

Este documento é um guia abrangente para a integração do Full IaaS. A partir de agora, sua empresa terá acesso ao universo de contas digitais por meio dos nossos serviços. Este material foi elaborado para orientar seu time de desenvolvimento a consumir nossas APIs e SDKs de maneira assertiva e bem-sucedida.

Durante o processo de integração, sua empresa conta com o suporte de nossa equipe especializada, que está disponível para esclarecer dúvidas técnicas, de jornada, regulatórias e quaisquer outras questões necessárias, através do Acionamento equipe Integração IaaS e pelo Atendimento ao cliente.

Conheça a jornada para integrar as soluções IaaS de ponta a ponta.

Certifique-se de atender aos seguintes requisitos para garantir a entrada em produção:

• Contrato Full IaaS assinado com a Franquia: Este contrato regula a relação entre o Itaú, como provedor de serviços BaaS, e as franquias, como contratantes. Ele define as regras, responsabilidades e o escopo do serviço a ser prestado. É um pré-requisito para iniciar as integrações.

• Termo de Uso: É obrigatório o Opt-in durante o Onboarding, e a franquia deve disponibilizar o termo para autosserviço (pós-onboarding).

• Setup Open Finance no Bacen: Há um processo inicial para habilitar a marca da franquia junto ao Bacen.

  • Devem ser definidos com a franquia o nome que será mostrado, a descrição da marca/empresa com até 255 caracteres e a logomarca, seguindo as orientações abaixo.

• Comprovantes: A franquia deve criar os comprovantes conforme os modelos enviados por e-mail. Após a elaboração, seguindo as orientações enviadas, que possuem campos específicos dependendo da modalidade de pagamento, os modelos devem ser submetidos à avaliação do Itaú para garantir conformidade.

• Configuração do OTP SMS e E-mail Personalizado: No processo de cadastro de chave Pix, é necessário parametrizar a mensageria via SMS e e-mail com a marca da franquia (autenticação de segundo fator). Dados exigidos:

  • Nome da empresa que aparecerá no SMS/E-mail.
  • Template com logomarca para construção do e-mail personalizado.

• Pentest: O teste de vulnerabilidade dos canais da franquia é um pré-requisito para a entrada em produção.

  • Exigência: A franquia deve apresentar um relatório elaborado pelo time de SI da franquia, seguindo os parâmetros do roteiro disponibilizado, que será avaliado pela SI Itaú. Dependendo do grau de vulnerabilidade, a franquia pode ser liberada para produção (risco baixo). Se o risco for médio ou alto, a produção é impedida até que os riscos sejam sanados.

• Análise de Front End: A franquia deve, ao concluir o design do front end, disponibilizá-lo para análise para garantir aderência às normativas. Toda nova jornada construída deve ser sempre disponibilizada ao Itaú para avaliação e autorização de produção.

Para iniciar a sua jornada de integração com o Full IaaS você deve:

• Ler a documentação Primeiros passos;
• Realizar o setup seguindo os passos da documentação de Certificado dinâmico.

Após concluir o processo de configuração do Certificado Dinâmico, é essencial que você envie as credenciais geradas para a equipe do IaaS por meio do e-mail integracaosetup@itau-unibanco.com.br. Esse processo gera um Client ID específico para o envio e renovação de certificados mTLS. Em seguida, a equipe do IaaS realizará as configurações adicionais necessárias para garantir o funcionamento correto do sistema.

Após a finalização dessas configurações, você receberá um e-mail da equipe do IaaS contendo as novas credenciais. Essas credenciais são essenciais para a integração e execução de chamadas transacionais e devem ser utilizadas no SDK de Autenticação e em todas as chamadas necessárias do IaaS. As credenciais fornecidas incluem:

• Client ID
• Secret

Para começar sua jornada com as APIs do Full IaaS, o primeiro passo é a autenticação. É essencial utilizar nosso SDK, que é independente do modelo (web ou mobile) que você escolher seguir. Com o autenticador Itaú, você pode implementar o modelo de negócio IaaS por meio de uma autenticação multiplataforma.

Utilize o Artifactory Edge para facilitar o acesso e a distribuição de bibliotecas, aprimorando a colaboração e a eficiência no desenvolvimento. Aqui, você encontra as versões mais recentes e atualizadas.

Existem duas jornadas para a autenticação:

Autenticação Web

Acesse em App Autenticador Financeiro.

O Autenticador Financeiro é um aplicativo de autenticação cross device, seguro e fácil de usar, projetado para fornecer uma camada extra de segurança para sua empresa. Utilizando recursos avançados de biometria, o aplicativo é capaz de verificar sua identidade de forma rápida e segura, garantindo que apenas você possa acessar suas informações e se autenticar para transações.

Autenticação Mobile

Acesse em SDK BaasAuth Nativo.

O BaasAuthSDK é utilizado como padrão IaaS de cadastro e autenticação de usuários para uso interno e externo ao Itaú, em aplicativos do Itaú ou parceiros externos, com a finalidade de garantir segurança em todas as transações realizadas para os serviços do Itaú.

Com a autenticação finalizada, caso contratado, integre-se a API Restritivos PF e PJ sendo a API responsável por analisar o Risco de Fraudes e/ou PLD, com base no conhecimento e histórico do banco, para aumentar a sua conversão de onboarding e facilitar a gestão de convites.

Então inicie a etapa de KYC, utilizando a API KYC (Know Your Customer). A API de Know Your Customer (KYC) reúne funcionalidades para cadastro de usuários de forma mais rápida e segura. São serviços de enriquecimento e validação de dados para garantir o onboarding de clientes aos serviços financeiros disponibilizados pelo IaaS.

Testes sugeridos para a implementação da API

Confira os testes sugeridos para se integrar a API de KYC:

Download da tabela de testes de KYC.

Ao completar com sucesso a etapa anterior implemente a API de IaaS - Onboarding - PF e PJ. A API de Onboarding IaaS é utilizada para disponibilizar serviços financeiros para seus clientes. Sendo possível solicitar a criação de uma conta de pagamento para pessoa física e conta corrente para pessoa jurídica. Para mais informações na integração com a conta vinculada acesse Manual de Integração Conta Vinculada IaaS.

Processo de onboarding

Para realizar o processo de onboarding, siga as etapas descritas a seguir:

1- Configuração de webhook: É necessário que a sua empresa disponibilize uma url para receber o resultado do processo de onboarding. Para mais informações acesse Webhook.

2- Validação e Enriquecimento de dados: Realize os processos de KYC para enviar documentos do cliente e validar os dados que serão utilizados na solicitação de onboarding.

3- Authorizer Onboarding: Antes de chamar o onboarding, é necessário realizar as chamadas para o Authorizer. Essa integração realiza a autenticação do cliente via login no ambiente do Itaú, permitindo que os dados dele sejam disponibilizados para uma instituição externa, de forma segura e com o seu consentimento.

4- Solicitação de Onboarding: Faça a chamada para a API de onboarding, de acordo com o serviço que deseja solicitar para o cliente. Atente-se às regras de cada parâmetro e envie o payload.

5- Análises de Segurança: Ao realizar uma chamada com sucesso, você receberá um onboarding_id. Esse código pode ser utilizado para verificar o status da solicitação, enquanto realizamos nossas análises de segurança. Para pessoa física, o processo pode levar até 5 minutos e, para pessoa jurídica, até 3 dias.

6- Retorno via Webhook: O resultado do onboarding chegará via webhook. Em caso de ambiente fora do ar, realizamos 5 tentativas com intervalos exponenciais. A última tentativa pode levar até 2 horas. Acesse Webhook para conhecer as possibilidades de retorno de sucesso e de erro no onboarding.

Ainda, dentro da etapa de onboarding, em caso de integração PJ, implemente também a API IaaS - Usuários e Perfis - PJ, responsável por disponibilizar serviços relacionados ao controle dos usuários e perfis da conta corrente de pessoa jurídica.

Testes sugeridos para a implementação da API

Confira os testes sugeridos para se integrar a API de Onboarding PF:

Download da tabela de testes do Onboarding PF.

Testes sugeridos para a implementação da API

Confira os testes sugeridos para se integrar a API de Onboarding PJ:

Download da tabela de testes do Onboarding PJ.

Com o onboarding concluído é preciso se integrar as APIs de gestão de contas, sendo elas:

• IaaS - Contas - PF e PJ
• IaaS - Saldo - PF e PJ
• IaaS - Extrato - PF e PJ
• IaaS - Comprovantes de pagamentos - PF e PJ
• IaaS - Contatos - PF e PJ
• IaaS - Limites - PF e PJ

Através dessas APIs é possível que você gerencie as contas criadas para os clientes da sua franquia de forma eficiente e segura. Com as funcionalidades:

• Consulta de saldo
• Consulta dados de uma conta
• Consulta extrato
• Consulta de comprovante
• Consulta de limite
• Encerramento de conta

Testes sugeridos para a implementação da API

Confira os testes sugeridos para se integrar a API de Accounts em caso de integração PF:

Download da tabela de testes de Gestão de Conta.

Em seguida, deve-se integrar a API do DICT que permite a gestão de chaves PIX e realiza as seguintes ações:

• Validar chave Pix
• Criar chave Pix
• Excluir chave Pix
• Buscar todas as chaves Pix de uma conta
• Solicitar reivindicação ou portabilidade de chave Pix
• Atualizar solicitações de reivindicação de posse ou portabilidade de chave

Testes sugeridos para a implementação da API

Confira os testes sugeridos para se integrar a API de DICT:

Download da tabela de testes de DICT.

Com o DICT integrado, siga para a integração do PIX transacional. As API IaaS - Pix Transacional PJ e PF tem como finalidade permitir o gerenciamento de pagamentos, agendamentos e devoluções via PIX.

Acesse IaaS - Pix Transacional PJ.

Acesse IaaS - Pix Transacional PF.

Em seguida aplique a consulta do PIX através do endpoint Busca todos os pagamentos PIX da conta.

Este endpoint retorna todos os pagamentos da conta baseado no contexto do token.

Então integre-se a API Qrcode Pix - PF e PJ responsável pela criação, decodificação, consulta e atualização de QR Codes.

Testes sugeridos para a implementação da API

Confira os testes sugeridos para se integrar as APIs de PIX:

Download da tabela de testes de PIX.

A seguir realize a integração com a API de PIX Automático, essa API permite a consulta, atualização, efetivação e cancelamento de autorizações de Pix automático, além de gerenciar agendamentos associados a essas autorizações.

As operações disponíveis para Gestão do Pix Automático estão divididas em segmentos:

• Consulta de autorizações: Realiza a consulta de autorizações.
• Consulta dos detalhes de uma autorização: Realiza a consulta dos detalhes de uma autorização.
• Efetivação de uma autorização: Realiza a efetivação de uma autorização após confirmação do cliente.
• Cancelamento de uma autorização: Realiza o cancelamento de uma autorização.
• Consulta de pagamentos agendados: Realiza a consulta de pagamentos agendados.
• Consulta dos detalhes de um pagamento agendado: Realiza a dos detalhes de um pagamento agendado.
• Cancelamento de um pagamento agendado: Realiza o cancelamento de pagamento agendado.

Para público PJ acesse Pix Automático Pagador PJ e para público PF acesse Pix Automático Pagador PF.

Pré-requisitos

Antes de iniciar a integração com as jornadas PIX PJ, é essencial garantir que todos os pré-requisitos estejam atendidos. Estes passos são fundamentais para assegurar que você tenha acesso completo às funcionalidades e possa realizar transações de forma eficiente e segura. A seguir estão os pré-requisitos necessários:

• Criar uma conta, através do processo de onboarding, para ser a conta de origem;
• Criar uma segunda conta, através do processo de onboarding, para ser conta de destino;
• Possuir o token de leitura;
• Possuir o token de escrita.

Pagamentos

Pagamento por chave PIX

Para realizar o pagamento por chave PIX, siga os passos a seguir:

1. Obtenha a chave PIX da conta destino;
2. Consulte os dados da chave PIX: Antes de realizar a transação, é necessário consultar os dados associados à chave PIX através do endpoint Consultar chave PIX. Durante essa consulta, você deve obter os seguintes parâmetros:
   • endToEndID: Este é o identificador único da transação, essencial para o rastreamento end-to-end.
   • destinationAccount: Este parâmetro apresenta os dados bancários do dono da chave PIX consultada.
3. Realize o Pagamento: Após obter os dados necessários, utilize o endpoint Realizar uma transferencia ou agendamento de PIX para efetuar o pagamento utilizando a chave PIX. Para consultar o exemplo de pagamento por chave pix selecione Efetivação de pagamento por chave PIX no Example de sandbox.

Pagamento por dados bancários

Para realizar o pagamento por dados bancários, siga os passos a seguir:

1. Obtenha os dados bancários para pagamento, sendo eles:
   • Agência: Rerpresentado pelo parâmetro branch;
   • Conta: Representado pelo parâmetro number;
   • Banco: Para que o usuário possa selecionar os bancos participantes utilize o endpoint Consultar bancos participantes do Arranjo PIX.
2. Realize o pagamento: A partir dos dados obtidos utilize o endpoint Realizar uma transferencia ou agendamento de PIX para efetuar o pagamento utilizando os dados bancários. Para consultar o exemplo de pagamento por dados bancários selecione Efetivação de pagamento por dados bancários no Example de sandbox.

Pagamento por QR Code

Para realizar o pagamento por QR Code, siga os passos a seguir:

1. Obtenha o QR Code para pagamento;
2. Decodifique os dados do QR Code: Antes de realizar a transação, é necessário consultar os dados associados ao QR Code através do endpoint Decodificar um QR Code.
3. Realize o pagamento: A partir dos dados obtidos utilize o endpoint Realizar uma transferencia ou agendamento de PIX para efetuar o pagamento utilizando o QR Code. Para consultar os exemplos de pagamento por QR Code selecione os exemplos que começarem por Efetivação de pagamento por QR Code no Example de sandbox.

Consulta de pagamentos

Para consultar os pagamentos e agendamentos realizados via PIX PJ, siga os passos a seguir:

1. Analise o extrato de pagamentos PIX: Inicie revisando o extrato de pagamentos para identificar as transações que deseja consultar;
2. Realize a consulta: Utilize a API Busca Pagamentos para obter informações detalhadas sobre as transações identificadas no extrato, através do transferID. Esta API permite o acesso aos dados específicos de cada pagamento e agendamento de pagamento, facilitando o acompanhamento e a gestão das transações.

Agendamento de pagamentos

Para agendar pagamentos via PIX PJ, siga os passos a seguir:

1. Defina uma data futura: Nos fluxos de pagamento disponíveis, utilize o campo transferAt para agendar uma data futura para a transação. Para consultar os exemplos de agendamento selecione os exemplos que começarem por Agendamento de pagamento no Example de sandbox.
2. Consulta de agendamento: Após o agendamento, você pode acompanhar a operação através do webhook, que fornece atualizações sobre o status do pagamento.
3. Cancelamento de agendamento: Caso precise cancelar o agendamento, utilize o endpoint Cancelar transação temporizada ou agendamento PIX de tipo MANUAL ou CHAVE ou o endpoint Cancelar um agendamento PIX de tipo QRCODE antes da data programada para garantir que a transação não seja processada.

Devolução de pagamentos

Para realizar a devolução de pagamentos via PIX PJ, siga os passos a seguir:

1. Realize o Cash In: Inicie o processo de devolução realizando ou recebendo o Cash In necessário.
2. Identifique o Cash In para Devolução: Utilize o extrato para localizar o Cash In que será devolvido.
3. Localize o lançamento: Encontre o ID do evento, eventUniqueId, através do endpoint Consultar lançamentos efetivados, então busque o lançamento correspondente no endpoint Buscar lançamento PIX para encontrar o entryID e o transferId.
4. Preencha a API de devolução: Com os dados obtidos, preencha a chamada do endpoint Efetuar devolução de uma transação PIX utilizando os três IDs necessários: transferId, paymentId (mesmo valor do transferId) e entryId, além do valor e da razão para a devolução.
5. Confirme a devolução: Após preencher os dados, confirme a operação para gerar a devolução.

Após a jornada do PIX implementada, siga para a jornada de boletos.

As API de Pagamento de Boletos PJ e PF tem como objetivo disponibilizar a usuários contratantes da solução a possibilidade de liquidar guias de pagamento de boletos de cobrança e/ou arrecadação (contas de água, luz, telefone e tributos).

Acesse IaaS - Pagamento de Boletos PJ.

Acesse Iaas - Pagamento de Boletos PF.

Testes sugeridos para a implementação da API

Confira os testes sugeridos para se integrar a API de Pagamento de boletos PF e PJ:

Download da tabela de testes de Pagamento de boletos.

Em caso de integração PF, implemente a API de DDA. Essa API tem como objetivo oferecer aos usuários contratantes da solução a funcionalidade de cadastrar, cancelar e consultar pagadores eletrônicos, além de listar boletos.

A seguir, conheça o fluxo recomendado para utilização dos endpoints da API de DDA:

1. Cadastre o pagador: Inicialmente, o pagador será cadastrado com status pendente.

• Endpoint: POST /payers

2. Consulte o pagador: Verifique se o pagador está ativo.

• Endpoint: GET /payer-details

3. Faça consultas do pagador a partir de uma conta: Verifique se o pagador está ativo a partir de uma conta específica.

• Endpoint: GET /payers

4. Delete o pagador ativo: Remova o pagador que está ativo.

• Endpoint: DELETE /payers

5. Consulte boletos: Verifique os boletos cadastrados.

• Endpoint: GET /bank-slips

6. Notifique novos boletos: Notifique novos boletos ao cliente final.

Testes sugeridos para a implementação da API

Confira os testes sugeridos para se integrar a API de DDA:

Download da tabela de testes de DDA.

Com as APIs anteriores integradas, implemente a API Consulta Pagamentos PJ, essa API tem como finalidade externalizar funções de consulta relativo aos pagamentos de uma conta PJ, bem como obter resumos de pagamentos através de filtros, consulta geral dos pagamentos e consulta detalhada do pagamento através de seu identificador único.

Com a integração da Consulta Pagamentos finalizada integre-se com a API Gestão de Cobrança PJ, responsável por realizar operações financeiras com boletos bancários e movimentações financeiras.

Confira o fluxo de utilização dos endpoints de gestão de cobrança:

1. O primeiro passo é emitir um boleto por meio do endpoint POST /bank-slips.
2. Em seguida, pode-se realizar consultas, que incluem consultas gerais, consulta de PDF e consulta de movimentações de cobrança por meio dos respectivos endpoints: GET /bank-slips/{bankSlipID}/details, GET /bank-slips/{bankSlipID}/pdfs, GET /calendars, GET statements, GET summaries.
3. Ao final, após um dia da emissão, é possível realizar a alteração e baixa de um boleto por meio do endpoint PATCH /bank-slips/{bankSlipId}/instructions/{instructionId}.

Testes sugeridos para a implementação da API

Confira os testes sugeridos para se integrar a API de Gestão de Cobrança PJ:

Download da tabela de testes de Gestão de Cobrança.

Após o passo anterior, caso contratado, integre-se a API Débitos Externos. Essa API oferece flexibilidade e facilidade para o pagamento pontual ou recorrente de qualquer produto ou serviço das franquias. Permite que o saldo disponível na conta de um cliente PF seja utilizado para diferentes jornadas de débito e realiza reversão total ou parcial do valor das transações realizadas.

Confira a seguir o passo a passo para se integrar com a API de Débitos Externos:

1. Setup do parceiro: É necessário obter credenciais de segurança para realizar chamadas para as APIs; configurar acesso à plataforma de envio dos relatórios; e disponibilizar uma url para receber o resultado das solicitações de débito ou reversão via webhook. Caso haja uma processadora terceira, este fornecedor deve realizar, também, seu próprio setup.

2. Configuração das jornadas de débito: Para cada jornada desejada, é necessário que o parceiro informe a conta PJ Itaú que será utilizada para aquele fluxo, além de informar se contará com um fornecedor externo para processar as transações. Confira mais detalhes na aba Jornadas de Débito.

3. Validações de segurança para a solicitação: Lembre-se que autenticação, análise de PLD, análise de fraudes e exigências jurídicas, como aceite de termos de uso, são de responsabilidade do parceiro ou da processadora terceira. Só realize a requisição de débito após realizar todas as validações necessárias.

4. Solicitação de débito: Faça a chamada para a API, de acordo com a jornada de débito. Atente-se às especificidades de cada contrato e envie o payload correspondente.

5. Retorno síncrono de processamento: Um retorno síncrono valida o payload da requisição e informa se a transação está sendo processada ou não.

6. Resultado da transação via Webhook: O resultado da solicitação chegará via webhook, em até 4 segundos. Clique em webhook no menu lateral para conhecer as possibilidades de retorno de sucesso e de erro de uma transação.

7. Se necessário, solicite a reversão: As reversões dos valores transacionados são, sempre, mediante solicitação do iniciador externo. Não possuímos cenários de reversão automática. É possível fazer a devolução do valor total ou parcial de uma transação realizada.

Então integre-se com o Open Finance. O Sistema Financeiro Aberto ou Open Finance, é um sistema onde os bancos e outras instituições financeiras (autorizadas a funcionar pelo Banco Central do Brasil) vão poder compartilhar em plataformas de tecnologia os dados sobre produtos e serviços financeiros dos clientes. Todas as instituições só podem compartilhar os mesmos dados, que foram escolhidos pelo Bacen e o cliente é quem decide se quer ou não que seus dados sejam compartilhados.

Em seguida, acesse API Informe Rendimentos - PF e PJ para se integrar a API de informe de rendimentos, responsável por solicitar o informe de rendimentos dos clientes da sua franquia.

Ao final, caso contratado, você deve se integrar as APIs de Atendimento.

• Atendimento Gestão de clientes PF
• Atendimento Gestão de tickets PF
• Atendimento Gestão de contas PF e PJ