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).

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 UBOs (para clientes empresariais)

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.

​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