Jornada de Onboarding - Guia Step-by-Step

Diagrama do Fluxo

Representação documental do fluxo de onboarding, baseada nas etapas descritas nesta jornada. O fluxo PF e PJ é simétrico (mesmas fases). Não substitui o contrato da API.

As etapas marcadas como opcional/configurável seguem o que os guias descrevem; a obrigatoriedade de cada passo depende da configuração do onboarding.

Este guia apresenta o fluxo completo de onboarding na Finway para Pessoa Física (PF) e Pessoa Jurídica (PJ), dividido em etapas claras e sequenciais para facilitar a implementação.

Visão Geral do Processo

O onboarding é dividido em duas fases principais para ambos os tipos de usuário:

Simple Onboarding - Registro inicial do usuário na plataforma (Obrigatório)
Ativação da Conta - Cadastro completo no provedor BaaS e criação da conta bancária (Configurável)

informação

Importante: A Fase 1 é obrigatória e deve seguir a ordem apresentada. A Fase 2 é configurável por cliente, podendo ter etapas opcionais e ordem flexível conforme a necessidade organizacional.

Pré-requisitos

Antes de iniciar, certifique-se de ter:

client_id configurado
client_secret para gerar tokens de autenticação
Ambiente de desenvolvimento/produção configurado

Onboarding PF (Pessoa Física)

Fase 1: Simple Onboarding (Obrigatório)

Passo 1: Gerar Token de Autenticação

Endpoint: POST /api/bank-services/security/auth/tokens

Primeiro passo obrigatório para todas as operações.

curl --location --request POST 'https://api-dev.finway.com.br/api/bank-services/security/auth/tokens' \
--header 'client_id: [seu_client_id]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "client_credentials",
    "client_id": "[seu_client_id]",
    "client_secret": "[seu_client_secret]"
}'

Resposta esperada:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
}

informação

Importante: Use o access_token no header x-buildersbank-authorization nas próximas requisições.

Passo 2: Criar Registro Inicial PF

Endpoint: POST /api/bank-services/simple-onboarding

Cria o registro inicial do usuário pessoa física com dados básicos.

{
    "nickname": "joao123",
    "name": "João Silva Santos",
    "document": "12345678901",
    "email": "joao@email.com",
    "password": "MinhaSenh@123",
    "deviceKey": "device-unique-key-123",
    "deviceIdentification": "iOS-iPhone-12",
    "transactionPassword": "1234"
}

Validações automáticas:

CPF válido e único
Email válido e único
Senha com critérios de segurança
Nome e nickname obrigatórios

Resposta: Token temporário para próximas etapas

{
    "token": "temp_token_para_validacoes"
}

Passo 3: Validação OTP (Configurável)

informação

Configurável: Cada cliente pode configurar se deseja validação apenas por SMS, apenas por Email, ou ambos.

Opção A: Validação por SMS

3.1 - Solicitar código SMS POST /api/bank-services/simple-onboarding/sms/otp/challenge

{
    "token": "temp_token_do_passo_anterior",
    "mobilePhone": "+5511999887766",
    "deviceIdentification": "iOS-iPhone-12"
}

3.2 - Validar código SMS POST /api/bank-services/simple-onboarding/sms/otp/validate

{
    "token": "temp_token_atualizado",
    "code": "123456"
}

Opção B: Validação por Email

3.1 - Solicitar código Email POST /api/bank-services/simple-onboarding/mail/otp/challenge

{
    "token": "temp_token_sms_validado",
    "mail": "joao@email.com",
    "deviceIdentification": "iOS-iPhone-12"
}

3.2 - Validar código Email POST /api/bank-services/simple-onboarding/mail/otp/validate

{
    "token": "temp_token_email",
    "code": "654321"
}

Configurações dos OTPs:

SMS: Código de 6 dígitos, TTL: 5 minutos, Máximo 3 tentativas
Email: Código de 6 dígitos, TTL: 10 minutos, Template personalizado

Passo 4: Upload de Documentos Básicos (Opcional)

Endpoint: POST /api/bank-services/simple-onboarding/documents

Upload de documentos básicos para validação inicial.

{
    "token": "temp_token_validado",
    "filename": "documento_identidade.jpg",
    "contentType": "image/jpeg",
    "type": "IDENTITY",
    "livenessProbability": 0.95,
    "biometricSimilarity": 0.89,
    "requestId": "req-123456789"
}

Tipos aceitos:

IDENTITY - Documento de identidade
CPF - Documento CPF
SELFIE - Selfie do usuário
PROOF_RESIDENCE - Comprovante de residência

Passo 5: Criar Conta Interna PF

Endpoint: POST /api/bank-services/simple-onboarding/accounts

Finaliza o Simple Onboarding criando a conta interna.

{
    "nickname": "joao123",
    "name": "João Silva Santos",
    "document": "12345678901",
    "email": "joao@email.com",
    "token": "temp_token_final"
}

Pré-requisitos:

OTP validado (SMS e/ou Email conforme configuração)
Token válido
Dados básicos aprovados

Fase 2: Ativação da Conta PF (Configurável)

informação

Flexível: As etapas abaixo são configuráveis por cliente. A ordem e quais etapas são obrigatórias dependem da organização e necessidades específicas de cada implementação.

Etapas Configuráveis

Obtenção de termos
Atualização de dados pessoais
Upload de documentos complementares
Ativação de produtos de crédito

Etapa Obrigatória

Criação da conta bancária é sempre obrigatória para finalizar o onboarding

Opção: Obter Termos e Condições PF

Endpoint: GET /api/bank-services/holders/{document}/terms

Obtém documentos regulamentares que devem ser aceitos.

GET /api/bank-services/holders/12345678901/terms
# ou
GET /api/bank-services/holders/me/terms

Resposta:

{
    "regulatoryDocuments": [
        {
            "id": "termo-conta-corrente-v1",
            "title": "Contrato de Conta Corrente",
            "mandatory": true,
            "url": "https://docs.finway.com.br/termo-conta-corrente.pdf"
        }
    ]
}

Opção: Atualizar Dados Pessoais PF

Endpoint: PATCH /api/bank-services/holders/{document}/personal/account

Atualiza informações pessoais completas para ativação.

{
    "motherName": "Maria Silva Santos",
    "birthdate": "1990-05-15",
    "address": {
        "zipCode": "01234567",
        "street": "Rua das Flores",
        "number": "123",
        "complement": "Apto 45",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
    },
    "pep": "NO",
    "declaredIncome": "FROM_5_TO_10",
    "revenueAmount": 7500,
    "nationality": "BRAZILIAN",
    "occupation": "EMPLOYEE",
    "agreeTerms": "termo-conta-corrente-v1,politica-privacidade-v2",
    "gender": "MALE",
    "email": "joao@email.com",
    "mobilePhone": "+5511999887766"
}

Validações:

Idade mínima (18 anos)
CPF consistente
Endereço válido via CEP
Aceite de termos obrigatórios

Opção: Upload de Documentos Complementares PF

Endpoint: POST /api/bank-services/holders/{document}/personal/account/documents

Upload de documentos para ativação da conta.

{
    "filename": "rg_frente.jpg",
    "contentType": "image/jpeg",
    "type": "IDENTITY_FRONT",
    "livenessProbability": 0.92,
    "biometricSimilarity": 0.87,
    "requestId": "upload-789012345"
}

Documentos aceitos:

IDENTITY_FRONT - Frente do RG/CNH
IDENTITY_BACK - Verso do RG/CNH
SELFIE_DOCUMENT - Selfie com documento
PROOF_RESIDENCE - Comprovante de residência
PROOF_INCOME - Comprovante de renda

OBRIGATÓRIO: Criar Conta Bancária PF

Endpoint: POST /api/bank-services/holders/{document}/personal/account/settlement

Finaliza criação da conta no core bancário.

{
    "pin": "1234"
}

Resultado:

Conta criada no core bancário
Número da conta gerado
Produtos básicos configurados
Limites iniciais definidos

Opção: Ativar Produtos de Crédito PF

Endpoint: POST /api/bank-services/holders/{document}/personal/account/credit

Cria e ativa produtos de crédito.

POST /api/bank-services/holders/me/personal/account/credit

Produtos inclusos:

Cartão de crédito
Limite para operações
Conta digital com recursos avançados

Análise automática:

Score de crédito
Histórico bancário
Definição de limite personalizado

Onboarding PJ (Pessoa Jurídica)

Fase 1: Simple Onboarding PJ (Obrigatório)

Passo 1: Gerar Token de Autenticação PJ

Endpoint: POST /api/bank-services/security/auth/tokens

Mesmo processo de autenticação para PJ.

curl --location --request POST 'https://api-dev.finway.com.br/api/bank-services/security/auth/tokens' \
--header 'client_id: [seu_client_id]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "client_credentials",
    "client_id": "[seu_client_id]",
    "client_secret": "[seu_client_secret]"
}'

informação

Importante: Use o access_token no header x-buildersbank-authorization nas próximas requisições.

Passo 2: Criar Registro Inicial PJ

Endpoint: POST /api/bank-services/simple-onboarding/business

Cria o registro inicial da empresa com dados básicos.

{
    "companyName": "Empresa Exemplo LTDA",
    "tradeName": "Empresa Exemplo",
    "document": "12345678000195",
    "email": "contato@empresaexemplo.com.br",
    "password": "MinhaSenh@123",
    "deviceKey": "device-unique-key-456",
    "deviceIdentification": "iOS-iPhone-12",
    "transactionPassword": "5678",
    "legalRepresentative": {
        "name": "João Silva Santos",
        "document": "12345678901",
        "email": "joao@empresaexemplo.com.br"
    }
}

Validações automáticas:

CNPJ válido e único
CPF do representante legal válido
Email válido e único
Senha com critérios de segurança
Razão social obrigatória

Resposta: Token temporário para próximas etapas

{
    "token": "temp_token_pj_validacoes"
}

Passo 3: Validação OTP PJ (Configurável)

informação

Configurável: Validação pode ser por SMS, Email ou ambos.

Validação por SMS (PJ)

3.1 - Solicitar código SMS POST /api/bank-services/simple-onboarding/business/sms/otp/challenge

{
    "token": "temp_token_pj_anterior",
    "mobilePhone": "+5511999887766",
    "deviceIdentification": "iOS-iPhone-12"
}

3.2 - Validar código SMS POST /api/bank-services/simple-onboarding/business/sms/otp/validate

{
    "token": "temp_token_pj_atualizado",
    "code": "123456"
}

Validação por Email (PJ)

3.1 - Solicitar código Email POST /api/bank-services/simple-onboarding/business/mail/otp/challenge

{
    "token": "temp_token_pj_sms_validado",
    "mail": "contato@empresaexemplo.com.br",
    "deviceIdentification": "iOS-iPhone-12"
}

3.2 - Validar código Email POST /api/bank-services/simple-onboarding/business/mail/otp/validate

{
    "token": "temp_token_pj_email",
    "code": "654321"
}

Passo 4: Upload de Documentos Básicos PJ (Opcional)

Endpoint: POST /api/bank-services/simple-onboarding/business/documents

Upload de documentos básicos da empresa.

{
    "token": "temp_token_pj_validado",
    "filename": "cartao_cnpj.pdf",
    "contentType": "application/pdf",
    "type": "CNPJ_CARD",
    "requestId": "req-pj-123456789"
}

Tipos aceitos para PJ:

CNPJ_CARD - Cartão CNPJ
SOCIAL_CONTRACT - Contrato social
LEGAL_REPRESENTATIVE_IDENTITY - Documento do representante legal
PROOF_ADDRESS - Comprovante de endereço da empresa

Passo 5: Criar Conta Interna PJ

Endpoint: POST /api/bank-services/simple-onboarding/business/accounts

Finaliza o Simple Onboarding criando a conta interna da empresa.

{
    "companyName": "Empresa Exemplo LTDA",
    "tradeName": "Empresa Exemplo",
    "document": "12345678000195",
    "email": "contato@empresaexemplo.com.br",
    "token": "temp_token_pj_final"
}

Pré-requisitos:

OTP validado (SMS e/ou Email conforme configuração)
Token válido
Dados básicos da empresa aprovados

Fase 2: Ativação da Conta PJ (Configurável)

Opção: Obter Termos e Condições PJ

Endpoint: GET /api/bank-services/business-holders/{document}/terms

Obtém documentos regulamentares específicos para PJ.

GET /api/bank-services/business-holders/12345678000195/terms

Resposta:

{
    "regulatoryDocuments": [
        {
            "id": "termo-conta-empresarial-v1",
            "title": "Contrato de Conta Empresarial",
            "mandatory": true,
            "url": "https://docs.finway.com.br/termo-conta-empresarial.pdf"
        }
    ]
}

Opção: Atualizar Dados Empresariais

Endpoint: PATCH /api/bank-services/business-holders/{document}/business/account

Atualiza informações completas da empresa.

{
    "foundationDate": "2020-01-15",
    "address": {
        "zipCode": "01234567",
        "street": "Rua Comercial",
        "number": "456",
        "complement": "Sala 12",
        "neighborhood": "Centro Empresarial",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
    },
    "businessActivity": "SOFTWARE_DEVELOPMENT",
    "monthlyRevenue": 50000,
    "legalRepresentative": {
        "name": "João Silva Santos",
        "document": "12345678901",
        "birthdate": "1985-03-20",
        "motherName": "Maria Silva Santos"
    },
    "agreeTerms": "termo-conta-empresarial-v1,politica-privacidade-pj-v2"
}

Opção: Upload de Documentos Complementares PJ

Endpoint: POST /api/bank-services/business-holders/{document}/business/account/documents

Upload de documentos para ativação da conta empresarial.

{
    "filename": "contrato_social.pdf",
    "contentType": "application/pdf",
    "type": "SOCIAL_CONTRACT",
    "requestId": "upload-pj-789012345"
}

Documentos aceitos para PJ:

SOCIAL_CONTRACT - Contrato social atualizado
CNPJ_REGISTRATION - Comprovante de inscrição CNPJ
LEGAL_REP_IDENTITY_FRONT - Frente do documento do representante
LEGAL_REP_IDENTITY_BACK - Verso do documento do representante
BUSINESS_PROOF_ADDRESS - Comprovante de endereço da empresa
FINANCIAL_STATEMENTS - Demonstrativo financeiro

OBRIGATÓRIO: Criar Conta Bancária PJ

Endpoint: POST /api/bank-services/business-holders/{document}/business/account/settlement

Finaliza criação da conta empresarial no core bancário.

{
    "pin": "5678"
}

Resultado:

Conta empresarial criada no core bancário
Número da conta gerado
Produtos empresariais configurados
Limites iniciais definidos

Opção: Ativar Produtos Empresariais

Endpoint: POST /api/bank-services/business-holders/{document}/business/account/credit

Cria e ativa produtos de crédito empresariais.

Produtos inclusos:

Cartão empresarial
Limite para operações
Conta digital com recursos empresariais
Antecipação de recebíveis

Análise automática:

Score empresarial
Faturamento declarado
Definição de limite personalizado

Resumo dos Fluxos

Fluxo PF vs PJ

Principais Diferenças

Aspecto	Pessoa Física (PF)	Pessoa Jurídica (PJ)
Documento	CPF (11 dígitos)	CNPJ (14 dígitos)
Endpoint Base	`/simple-onboarding`	`/simple-onboarding/business`
Dados Principais	Nome, CPF, Email	Razão Social, CNPJ, Repr. Legal
Documentos	RG, CPF, Selfie	Contrato Social, CNPJ, Doc. Repr.
Conta Bancária	Conta pessoal	Conta empresarial
Produtos	Pessoais	Empresariais

Fluxo Mínimo

PF - Etapas Obrigatórias:

Gerar token de autenticação
Criar registro inicial PF
Validar OTP (SMS ou Email)
Criar conta interna PF
Criar conta bancária PF

PJ - Etapas Obrigatórias:

Gerar token de autenticação
Criar registro inicial PJ
Validar OTP (SMS ou Email)
Criar conta interna PJ
Criar conta bancária PJ

Configurações OTP

Opções de validação disponíveis para PF e PJ:

Configuração	SMS	Email	Observações
Apenas SMS	Sim	Nao	Mais rápido, menor fricção
Apenas Email	Nao	Sim	Melhor para usuários sem celular
Ambos (Dupla)	Sim	Sim	Maior segurança, mais fricção

A configuração é definida por cliente na implementação.

Códigos de Erro Comuns

Código	Descrição	Solução
`CONFLICT`	CPF/CNPJ ou email já existe	Verificar dados ou usar recuperação
`INVALID_OTP`	Código OTP inválido	Solicitar novo código
`TOO_MANY_ATTEMPTS`	Muitas tentativas	Aguardar período de cooldown
`VALIDATION_ERROR`	Dados inválidos	Verificar formato dos campos
`PREREQUISITES_NOT_MET`	Etapas anteriores incompletas	Completar passos obrigatórios
`INVALID_CNPJ`	CNPJ inválido ou inativo	Verificar situação na Receita Federal
`LEGAL_REP_REQUIRED`	Representante legal obrigatório	Incluir dados do representante

Próximos Passos

Após o onboarding bem-sucedido, o usuário pode acessar:

Jornada de Login/Logout - Autenticação e gestão de sessões
Jornadas de PIX - Enviar e receber PIX
Jornadas de Transações - Transferências e pagamentos
Consulta de saldo e extrato
Gestão de conta e perfil

Para detalhes completos de cada endpoint, consulte a documentação da API.

Diagrama do Fluxo​

Visão Geral do Processo​

Pré-requisitos​

Onboarding PF (Pessoa Física)

Fase 1: Simple Onboarding (Obrigatório)​

Opção A: Validação por SMS​

Opção B: Validação por Email​

Configurações dos OTPs:​

Fase 2: Ativação da Conta PF (Configurável)​

Etapas Configuráveis​

Etapa Obrigatória​

Onboarding PJ (Pessoa Jurídica)

Fase 1: Simple Onboarding PJ (Obrigatório)​

Validação por SMS (PJ)​

Validação por Email (PJ)​

Fase 2: Ativação da Conta PJ (Configurável)​

Resumo dos Fluxos​

Principais Diferenças​

PF - Etapas Obrigatórias:​

PJ - Etapas Obrigatórias:​

Códigos de Erro Comuns​

Próximos Passos​

Diagrama do Fluxo

Visão Geral do Processo

Pré-requisitos

Fase 1: Simple Onboarding (Obrigatório)

Opção A: Validação por SMS

Opção B: Validação por Email

Configurações dos OTPs:

Fase 2: Ativação da Conta PF (Configurável)

Etapas Configuráveis

Etapa Obrigatória

Fase 1: Simple Onboarding PJ (Obrigatório)

Validação por SMS (PJ)

Validação por Email (PJ)

Fase 2: Ativação da Conta PJ (Configurável)

Resumo dos Fluxos

Principais Diferenças

PF - Etapas Obrigatórias:

PJ - Etapas Obrigatórias:

Códigos de Erro Comuns

Próximos Passos