Cadastre Clientes com um Link de KYC Hospedado

A integração por link hospedado é a forma mais rápida de cadastrar clientes (customer) no SpherePay. Em vez de construir uma UI de verificação personalizada, você cria um cliente via API, obtém um link hospedado e redireciona seu cliente para completar toda a verificação em uma página gerenciada pelo SpherePay. A experiência hospedada cuida do upload de documentos, verificação de vivacidade facial e todas as perguntas obrigatórias em um único fluxo. Esta abordagem funciona tanto para clientes pessoas físicas (KYC) quanto para clientes empresariais (KYB). Links de verificação hospedados coletam os dados adicionais de KYC e KYB da EEA+ automaticamente quando se aplicam — integradores que usam links hospedados não precisam de alterações de API para esses requisitos.

Use a abordagem de link hospedado para a integração mais rápida. Ela exige trabalho mínimo de frontend — você só gerencia a chamada inicial de API e o redirecionamento.

Quando usar esta abordagem

O link hospedado é ideal quando:

Você deseja integrar rapidamente sem construir uma UI de onboarding personalizada
Você prefere delegar o upload de documentos, verificações de vivacidade e OTP ao SpherePay
Você está prototipando ou fazendo um lançamento inicial antes de investir em um fluxo totalmente personalizado

Se você precisar de controle total sobre a experiência de coleta de dados ou quiser incorporar etapas de verificação diretamente no seu produto, use a integração baseada em API.

Escolha um único método de integração para cada cliente. Não misture o link hospedado e as abordagens de API para o mesmo cliente, nem recorra a um se o outro falhar — isso resultará em um onboarding malsucedido.

Como funciona

Você chama POST /v2/customer para criar um registro de cliente com dados básicos de contato.
Você chama o endpoint do link de TOS em paralelo para gerar um link de aceitação dos Termos de Serviço.
Você chama o endpoint do link de KYC/KYB para gerar um link de verificação hospedado.
Você redireciona ou envia o link ao seu cliente.
O cliente completa todo o processo de verificação na página hospedada.
Você consulta GET /v2/customer/{id} para detectar quando o perfil de verificação atingir approved.

Guia passo a passo

Criar um cliente

Chame POST /v2/customer com as informações básicas de contato e endereço do cliente. Para o caminho de link hospedado, você não precisa incluir personalInformation — o cliente insere essas informações na página hospedada.Para clientes pessoas físicas:

{
  "type": "individual",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "address": {
    "line1": "233 South Wacker Drive",
    "line2": "Suite 4700",
    "city": "Chicago",
    "postalCode": "60606",
    "state": "IL",
    "country": "USA"
  }
}

Para clientes empresariais:

{
  "type": "business",
  "email": "contact@acmecorp.example.com",
  "phone": "+14155551234",
  "addresses": [
    {
      "type": "registered",
      "country": "USA",
      "line1": "123 Main Street",
      "city": "Chicago",
      "state": "IL",
      "postalCode": "60601"
    },
    {
      "type": "operating",
      "country": "USA",
      "line1": "456 Market Street",
      "city": "Chicago",
      "state": "IL",
      "postalCode": "60602"
    }
  ]
}

Salve o id da resposta — você precisará dele nas próximas etapas.

Gerar um link dos Termos de Serviço

Gere um link de TOS e redirecione o cliente para aceitar os Termos e Condições. Esta etapa pode ser feita em paralelo com a geração do link de KYC/KYB.

POST https://api.spherepay.co/v2/customer/{id}/tos-link

Redirecione o cliente para a URL retornada para completar a aceitação do TOS.

Gerar o link hospedado de KYC ou KYB

Em paralelo com a etapa de TOS, gere o link de verificação hospedado para o seu cliente.

POST https://api.spherepay.co/v2/customer/{id}/kyc-link

Este endpoint único funciona tanto para clientes pessoas físicas (KYC) quanto para clientes empresariais (KYB) — o SpherePay determina o fluxo correto com base no type do cliente.Assim que o link for gerado, redirecione o cliente para a URL retornada. A experiência hospedada cuida de:

Upload de documentos (documento de identidade, comprovante de endereço)
Verificação de vivacidade facial
Verificação de contato por OTP
Upload de documentos empresariais e registro de pessoas associadas (para clientes empresariais)
Campos adicionais de KYC/KYB da EEA+ quando a residência ou o endereço registrado do cliente está na região EEA+

Links de verificação hospedados coletam os novos dados EEA+ automaticamente. Integradores que usam links hospedados não precisam de alterações de API para esses requisitos.

Durante o fluxo de KYC/KYB, o cliente pode registrar uma conta bancária. Ela permanecerá com status pending até que a identidade seja totalmente verificada e o perfil de verificação atingir approved.

Redirecionar ou enviar o link ao seu cliente

Redirecione o cliente diretamente da sua aplicação ou envie o link via e-mail ou SMS. O cliente não precisa ter uma conta SpherePay existente para completar a verificação hospedada.

Consultar o status de verificação

Após o cliente completar o fluxo hospedado, consulte GET /v2/customer/{id} até que status em verificationProfiles atinja approved.

GET https://api.spherepay.co/v2/customer/{id}

{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "approved",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number",
          "identity_document",
          "liveness_report_document"
        ],
        "pending": [],
        "required": [],
        "errors": []
      }
    }
  ],
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-03-09T20:46:31.305Z",
  "type": "individual"
}

Quando required estiver vazio e status for approved, o cliente está totalmente cadastrado e pronto para transferir.

Consulte em um intervalo razoável — por exemplo, a cada 30 segundos — em vez de continuamente. Você também pode usar webhooks se sua integração os suportar.

Próximos passos

Assim que o perfil de verificação do cliente estiver approved, registre seus métodos de pagamento e inicie uma transferência.

Contas bancárias

Registre uma conta bancária para que o cliente possa enviar ou receber fundos via rail bancário.

Carteiras

Registre um endereço de carteira cripto para habilitar transferências de on-ramp e off-ramp.

API de Transferências

Crie e gerencie transferências assim que o cliente tiver registrado seus métodos de pagamento.

Perfil de verificação

Entenda os status de verificação, arrays de critérios e o que desencadeia mudanças de estado.

Onboarding

Transferências

Automação

Webhooks

Dados de referência

Operacional

Cadastre Clientes com um Link de KYC Hospedado

Quando usar esta abordagem

Como funciona

Guia passo a passo

Próximos passos

Contas bancárias

Carteiras

API de Transferências

Perfil de verificação

​Quando usar esta abordagem

​Como funciona

​Guia passo a passo

​Próximos passos

Contas bancárias

Carteiras

API de Transferências

Perfil de verificação

Quando usar esta abordagem

Como funciona

Guia passo a passo

Próximos passos