> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Cadastre Clientes com um Link de KYC Hospedado
> Use o link de onboarding hospedado do SpherePay para verificar clientes sem construir uma UI personalizada. Conclua KYC ou KYB em poucos minutos.
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](/pt-BR/concepts/onboarding/individual-kyc).
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
1. Você chama `POST /v2/customer` para criar um registro de cliente com dados básicos de contato.
2. Você chama o endpoint do link de TOS em paralelo para gerar um link de aceitação dos Termos de Serviço.
3. Você chama o endpoint do link de KYC/KYB para gerar um link de verificação hospedado.
4. Você redireciona ou envia o link ao seu cliente.
5. O cliente completa todo o processo de verificação na página hospedada.
6. Você consulta `GET /v2/customer/{id}` para detectar quando o perfil de verificação atingir `approved`.
***
## Guia passo a passo
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:**
```json theme={"dark"}
{
"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:**
```json theme={"dark"}
{
"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.
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.
```bash theme={"dark"}
POST https://api.spherepay.co/v2/customer/{id}/tos-link
```
Redirecione o cliente para a URL retornada para completar a aceitação do TOS.
Em paralelo com a etapa de TOS, gere o link de verificação hospedado para o seu cliente.
```bash theme={"dark"}
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`.
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.
Após o cliente completar o fluxo hospedado, consulte `GET /v2/customer/{id}` até que `status` em `verificationProfiles` atinja `approved`.
```bash theme={"dark"}
GET https://api.spherepay.co/v2/customer/{id}
```
```json theme={"dark"}
{
"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.
Registre uma conta bancária para que o cliente possa enviar ou receber fundos via rail bancário.
Registre um endereço de carteira cripto para habilitar transferências de on-ramp e off-ramp.
Crie e gerencie transferências assim que o cliente tiver registrado seus métodos de pagamento.
Entenda os status de verificação, arrays de critérios e o que desencadeia mudanças de estado.