> ## Documentation Index > Fetch the complete documentation index at: https://laas.mippo.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Modelos de onboarding KYC e fluxos de transação > Compare os modelos KYC/AML do Supercosmos for Platforms — Direct Onboard, Client via Platform e Shared Onboard — com diagramas de sequência e fluxos de liquidação Pix. O Supercosmos for Platforms oferece três modelos de KYC/AML. Escolha o que se encaixa na sua estrutura de compliance atual. O fluxo de liquidação da transação (Pix → stablecoin) é idêntico nos três modelos; apenas a etapa de KYC muda. Cada plataforma é responsável por avaliar as próprias obrigações regulatórias. > [!NOTE] > > Todos os diagramas de sequência abaixo mostram as **chamadas de método do SDK** à esquerda e os **endpoints da API subjacentes** à direita. O SDK é apenas uma camada fina — você pode chamar a API REST diretamente, se preferir. *** ## Modelo 1 — Direct Onboard O Supercosmos executa todo o fluxo de KYC/AML. Seu aplicativo coleta CPF, selfie e endereço da carteira; o Supercosmos cuida do restante. Ideal para plataformas que estão lançando sem um fornecedor de KYC já contratado. **Quem executa o KYC:** Supercosmos ```mermaid theme={null} sequenceDiagram autonumber actor User participant App as Platform App / Backend participant SDK as Supercosmos SDK participant API as Supercosmos API participant Sumsub participant BCB as BCB / Pix Network participant Wallet as User Wallet User->>App: Inicia compra Pix → stablecoin App->>SDK: mippo.kyc.submit({ cpf, biometricHash, personType }) SDK->>API: POST /v1/laas/kyc/submit API->>Sumsub: Verificação biométrica + documental Sumsub-->>API: Resultado da verificação API->>API: Triagem de sanções (OFAC / COAF / ONU) API->>API: Classificação de PEP API-->>SDK: { token, riskTier: "STANDARD" | "HIGH" | "PEP" } SDK-->>App: kycToken, riskTier App->>SDK: mippo.transactions.initiate({ kycToken, amountBrl, asset, walletAddress }) SDK->>API: POST /v1/laas/transactions/initiate API-->>SDK: { transactionId, authChallenge } SDK-->>App: authChallenge alt riskTier = STANDARD → MFA (TOTP) App->>User: Solicita código TOTP User->>App: Informa o código TOTP App->>SDK: mippo.transactions.confirmMfa({ transactionId, totpCode }) SDK->>API: POST /v1/laas/transactions/:id/mfa API-->>SDK: { pixPayload, pixQrCode } SDK-->>App: pixPayload else riskTier = HIGH ou PEP → Prova de vida App->>User: Redireciona para authChallenge.livenessUrl User->>API: Conclui prova de vida (Sumsub WebSDK) API-->>App: webhook transaction.mfa_cleared App->>SDK: mippo.transactions.status(transactionId) SDK->>API: GET /v1/laas/transactions/:id/status API-->>SDK: { status: "AWAITING_PIX", pixPayload } SDK-->>App: pixPayload end App->>User: Renderiza QR code Pix / string Copia e Cola User->>BCB: Paga via Pix a partir de qualquer banco brasileiro BCB-->>API: Pagamento confirmado API->>API: Verificação de risco on-chain (KYT) sobre walletAddress API->>Wallet: Envia stablecoin (USDT / USDC) API->>App: POST webhook: transaction.completed { txHash, amount, walletAddress } App->>User: Exibe confirmação ``` > [!TIP] > > No sandbox, use o CPF `000.000.001-91` para forçar `riskTier: "HIGH"` e exercitar o caminho de prova de vida. *** ## Modelo 2 — Client via Platform Sua plataforma já executa o KYC com um fornecedor próprio (por exemplo, Idwall, unico check ou Sumsub diretamente). O Supercosmos aceita seu token de KYC, aplica uma triagem independente de sanções e KYT e então emite o próprio `kycToken` para prosseguir. **Quem executa o KYC:** Plataforma (principal) + Supercosmos (triagem independente) ```mermaid theme={null} sequenceDiagram autonumber actor User participant App as Platform App / Backend participant PartnerKYC as Platform KYC Vendor participant SDK as Supercosmos SDK participant API as Supercosmos API participant BCB as BCB / Pix Network participant Wallet as User Wallet User->>App: Conclui KYC na plataforma App->>PartnerKYC: Fluxo padrão de KYC (CPF, documento, prova de vida) PartnerKYC-->>App: partnerKycToken (emitido pelo fornecedor) Note over App,API: A plataforma repassa o token de KYC ao Supercosmos — sem reenvio de biometria App->>SDK: mippo.kyc.submit({ partnerKycToken, cpf, personType }) SDK->>API: POST /v1/laas/kyc/submit API->>API: Valida assinatura do partnerKycToken API->>API: Triagem independente de sanções (OFAC / COAF / ONU) API->>API: Classificação de PEP API-->>SDK: { token, riskTier } SDK-->>App: kycToken, riskTier App->>SDK: mippo.transactions.initiate({ kycToken, amountBrl, asset, walletAddress }) SDK->>API: POST /v1/laas/transactions/initiate API-->>SDK: { transactionId, authChallenge } SDK-->>App: authChallenge alt riskTier = STANDARD → MFA (TOTP) App->>User: Solicita código TOTP User->>App: Informa o código TOTP App->>SDK: mippo.transactions.confirmMfa({ transactionId, totpCode }) SDK->>API: POST /v1/laas/transactions/:id/mfa API-->>SDK: { pixPayload } SDK-->>App: pixPayload else riskTier = HIGH ou PEP → Prova de vida (do Supercosmos) App->>User: Redireciona para authChallenge.livenessUrl User->>API: Conclui a prova de vida do Supercosmos API-->>App: webhook transaction.mfa_cleared App->>SDK: mippo.transactions.status(transactionId) SDK->>API: GET /v1/laas/transactions/:id/status API-->>SDK: { pixPayload } SDK-->>App: pixPayload end App->>User: Renderiza QR code Pix User->>BCB: Paga via Pix BCB-->>API: Pagamento confirmado API->>API: Verificação de risco da carteira (KYT) API->>Wallet: Envia stablecoin API->>App: POST webhook: transaction.completed App->>User: Exibe confirmação ``` > [!WARNING] > > Um `partnerKycToken` **não** dispensa a triagem independente do Supercosmos. Se o Supercosmos detectar uma correspondência em listas de sanções que seu fornecedor não capturou, `kyc.submit` retorna `KYC_REJECTED` com `reason: "SANCTIONS_HIT"`. Veja as [Notas de Compliance](https://laas.mippo.io/docs/guides/compliance.md) para detalhes. *** ## Modelo 3 — Shared Onboard As duas camadas contribuem para o KYC. Seu aplicativo coleta CPF e dados básicos; o Supercosmos coleta a biometria (via Sumsub WebSDK embedado na sua interface). Um cruzamento dos dois conjuntos de dados produz o resultado conjunto de KYC. **Quem executa o KYC:** Plataforma (CPF + documento) + Supercosmos (biometria + prova de vida) ```mermaid theme={null} sequenceDiagram autonumber actor User participant App as Platform App / Backend participant SumsubWidget as Sumsub WebSDK (embedded) participant SDK as Supercosmos SDK participant API as Supercosmos API participant BCB as BCB / Pix Network participant Wallet as User Wallet User->>App: Inicia o onboarding App->>User: Coleta CPF + documento (fluxo da plataforma) User-->>App: CPF, imagem do documento Note over App,SumsubWidget: A plataforma embarca o Sumsub WebSDK apenas para a etapa de biometria App->>SumsubWidget: Inicia captura de prova de vida / selfie User->>SumsubWidget: Conclui a captura biométrica SumsubWidget-->>App: biometricHash (do callback do Sumsub) App->>SDK: mippo.kyc.submit({ cpf, biometricHash, personType, mode: "shared" }) SDK->>API: POST /v1/laas/kyc/submit API->>API: Cruzamento de CPF (dados da plataforma) vs biometria (dados Supercosmos/Sumsub) API->>API: Triagem de sanções (OFAC / COAF / ONU) API->>API: Classificação de PEP API-->>SDK: { token, riskTier } SDK-->>App: kycToken, riskTier App->>SDK: mippo.transactions.initiate({ kycToken, amountBrl, asset, walletAddress }) SDK->>API: POST /v1/laas/transactions/initiate API-->>SDK: { transactionId, authChallenge } SDK-->>App: authChallenge alt riskTier = STANDARD → MFA (TOTP) App->>User: Solicita código TOTP User->>App: Informa o código TOTP App->>SDK: mippo.transactions.confirmMfa({ transactionId, totpCode }) SDK->>API: POST /v1/laas/transactions/:id/mfa API-->>SDK: { pixPayload } SDK-->>App: pixPayload else riskTier = HIGH ou PEP → Prova de vida adicional necessária App->>User: Redireciona para authChallenge.livenessUrl User->>API: Conclui a prova de vida adicional API-->>App: webhook transaction.mfa_cleared App->>SDK: mippo.transactions.status(transactionId) SDK->>API: GET /v1/laas/transactions/:id/status API-->>SDK: { pixPayload } SDK-->>App: pixPayload end App->>User: Renderiza QR code Pix User->>BCB: Paga via Pix BCB-->>API: Pagamento confirmado API->>API: Verificação de risco da carteira (KYT) API->>Wallet: Envia stablecoin API->>App: POST webhook: transaction.completed App->>User: Exibe confirmação ``` > [!NOTE] > > No modo Shared, o Supercosmos gera um `applicantId` no Sumsub para você quando `kyc.submit` é chamado. Basta enviar o `biometricHash` — o SDK cuida do embedding do Sumsub automaticamente. *** ## Estados da transação Independentemente do modelo, toda transação percorre a mesma máquina de estados após o KYC ser aprovado: ```mermaid theme={null} stateDiagram-v2 [*] --> CREATED: transactions.initiate() CREATED --> AWAITING_MFA: Auth challenge emitido AWAITING_MFA --> AWAITING_PIX: MFA / prova de vida aprovada AWAITING_PIX --> PROCESSING: Pagamento Pix detectado PROCESSING --> COMPLETED: Stablecoin liquidada on-chain PROCESSING --> FAILED: Erro de liquidação (auto-retry x3) AWAITING_MFA --> EXPIRED: Sem resposta de MFA em 15 min AWAITING_PIX --> EXPIRED: Sem pagamento Pix em 30 min FAILED --> [*] EXPIRED --> [*] COMPLETED --> [*] ``` Faça polling em `mippo.transactions.status(transactionId)` ou escute os webhooks — veja o [guia de Webhooks](https://laas.mippo.io/docs/guides/webhooks.md) para a referência dos eventos. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.