Perfil de Verificação e Status do Cliente

Um perfil de verificação é um registro dos requisitos que o SpherePay precisa para aprovar um cliente (customer) — pessoa física ou jurídica — antes que ele possa iniciar ou receber transferências. Ele é retornado como parte do array verificationProfiles sempre que você chama GET /v2/customer/{id}. Monitorar o perfil de verificação é a principal forma de determinar se um cliente está pronto para transferir. A maioria das integrações verá um único perfil no array verificationProfiles. Um cliente está pronto para transferir quando o status desse perfil atingir approved. Se você encontrar nomes de perfil inesperados, entre em contato com seu representante do SpherePay.

Diferentes perfis de verificação desbloqueiam diferentes capacidades de transferência. Por exemplo, transferências em USD/EUR usam kyc_profile_a, enquanto transferências em BRL/PIX exigem kyc_profile_b — um caminho de onboarding separado. Entre em contato com seu representante do SpherePay para entender quais perfis se aplicam à sua integração.

Status de verificação

O campo status em um perfil de verificação tem quatro valores possíveis.

Status	Descrição	Pode iniciar transferências?
`incomplete`	O cliente ainda não completou todos os requisitos de verificação. Este é o estado inicial.	Não
`pending`	O cliente completou todos os requisitos e está aguardando a análise do SpherePay.	Não
`approved`	O SpherePay aprovou o cliente. Ele está totalmente cadastrado e pode iniciar transferências.	Sim
`rejected`	O SpherePay não pôde aprovar o cliente com base nas informações enviadas.	Não

Ciclo de vida do status

Um perfil de verificação avança pelos estados na seguinte ordem:

incomplete → pending → approved
                    ↘
                     rejected

O cliente começa em incomplete. O array criteria.required lista todos os requisitos pendentes.
Assim que todos os requisitos forem atendidos, o SpherePay processa automaticamente a verificação e move o perfil para pending. Nenhuma chamada de submit é necessária.
O SpherePay conclui a análise e transiciona o perfil para approved ou rejected.

Arrays de critérios de verificação

Cada perfil de verificação contém um objeto criteria com quatro arrays que descrevem o estado atual de cada requisito.

Array	Descrição
`complete`	Requisitos que foram atendidos. Nenhuma ação adicional necessária.
`pending`	Requisitos atualmente sendo processados pelo SpherePay. Aguarde a resolução.
`required`	Requisitos que ainda precisam ser completados. Você ou seu cliente devem agir sobre estes.
`errors`	Requisitos com erros de validação. Corrija-os antes de reenviar.

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

O que desencadeia transições de estado

Ação	Efeito
Criação do cliente com e-mail, telefone e endereço	Popula `complete` para `email_address`, `phone_number`, `residential_address`
Upload de documento de identidade	Move `identity_document` de `required` para `pending`, depois para `complete` após o processamento
Upload de relatório de vivacidade ou conclusão da verificação de vivacidade facial	Atende ao requisito `liveness_report_document` ou `liveness_check`
Aceitação do TOS via link hospedado	Atende ao requisito `terms_of_service`
Todos os itens de `required` resolvidos	O SpherePay envia automaticamente para análise; o status muda para `pending`
Análise manual concluída pelo SpherePay	O status muda para `approved` ou `rejected`

Como verificar o status de verificação

Chame GET /v2/customer/{id} para recuperar o estado atual do perfil de verificação de um cliente.

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"
}

Consulte GET /v2/customer/{id} para detectar quando a aprovação ocorrer, depois prossiga com o registro do método de pagamento e a configuração da transferência.

Campos do perfil de verificação — clientes pessoas físicas

Cada item nos arrays criteria corresponde a um requisito específico. A tabela abaixo descreve cada campo e qual ação o resolve.

Item	Ação necessária
`email_address`	Forneça um endereço de e-mail ao criar ou atualizar o cliente
`phone_number`	Forneça um número de telefone ao criar ou atualizar o cliente
`residential_address`	Forneça um endereço residencial completo ao criar ou atualizar o cliente
`tax_identification_number`	Forneça um ID fiscal via `personalInformation.taxIdentificationNumber`
`identity_document`	Faça upload de um documento de identidade emitido pelo governo via `POST /v2/document`
`liveness_report_document`	Faça upload de um relatório de vivacidade do seu provedor de KYC via `POST /v2/document`
`liveness_check`	Complete a verificação de vivacidade facial via link de `POST /v2/enhanced-due-diligence/face-verification-link` — avançado, obrigatório apenas para algumas integrações
`terms_of_service`	Aceite o TOS via link hospedado de `POST /v2/customer/{id}/tos-link` — avançado, obrigatório apenas para algumas integrações
`email_verification`	Verifique o e-mail via endpoints de envio e verificação de OTP — avançado, obrigatório apenas para algumas integrações
`phone_verification`	Verifique o telefone via endpoints de envio e verificação de OTP — avançado, obrigatório apenas para algumas integrações

Campos do perfil de verificação — clientes empresariais

Item	Ação necessária
`email_address`	Forneça um endereço de e-mail ao criar ou atualizar o cliente
`phone_number`	Forneça um número de telefone ao criar ou atualizar o cliente
`operating_address`	Forneça um endereço operacional no array `addresses`
`registered_address`	Forneça um endereço registrado no array `addresses`
`legal_name`	Forneça `businessInformation.legalName`
`trade_name`	Forneça `businessInformation.tradeName`
`entity_type`	Forneça `businessInformation.entityType`
`description`	Forneça `businessInformation.description`
`naics_code`	Forneça `businessInformation.naicsCode`
`website`	Forneça `businessInformation.website`
`incorporated_on`	Forneça `businessInformation.incorporatedOn`
`identification_number`	Forneça `businessInformation.identificationNumber` — tipos variam por país
`estimated_annual_revenue`	Forneça `businessInformation.estimatedAnnualRevenueInUsd`
`expected_monthly_payments`	Forneça `businessInformation.expectedMonthlyPaymentsInUsd`
`account_purpose`	Forneça `businessInformation.accountPurpose`
`source_of_funds`	Forneça `businessInformation.primarySourceOfFunds`
`regulated_activities`	Forneça `businessInformation.regulatedActivities`
`business_representatives`	Registre e verifique todos os UBOs via `POST /v2/business-representative`
`incorporation_cert_document`	Faça upload via `POST /v2/document` com `documentType: "incorporation_certificate"`
`shareholder_registry_document`	Faça upload via `POST /v2/document` com `documentType: "shareholder_registry"`
`proof_of_address_document`	Faça upload via `POST /v2/document` com `documentType: "proof_of_address"`
`terms_of_service`	Aceite o TOS via link hospedado — avançado, obrigatório apenas para algumas integrações
`master_service_agreement`	Assine o MSA via formulário hospedado apresentado após a aceitação do TOS — avançado, obrigatório apenas para algumas integrações

Tratamento de clientes rejeitados

Um status rejected significa que a verificação não pôde ser aprovada com base nas informações enviadas. Clientes com um perfil rejected não podem iniciar ou receber transferências. Se um cliente for incorretamente rejeitado ou precisar de reanálise, entre em contato com support@spherepay.co com o customerId.

Guias relacionados

KYC Individual

Guia passo a passo para cadastrar clientes pessoas físicas via API.

KYB Empresarial

Guia passo a passo para cadastrar clientes empresariais via API.

KYC via link hospedado

Cadastre clientes usando a experiência de verificação hospedada do SpherePay.

Visão geral de clientes

Visão geral de tipos de clientes, modelos de onboarding e métodos de integração.

​Status de verificação

​Ciclo de vida do status

​Arrays de critérios de verificação

​O que desencadeia transições de estado

​Como verificar o status de verificação

​Campos do perfil de verificação — clientes pessoas físicas

​Campos do perfil de verificação — clientes empresariais

​Tratamento de clientes rejeitados

​Guias relacionados

KYC Individual

KYB Empresarial

KYC via link hospedado

Visão geral de clientes

Status de verificação

Ciclo de vida do status

Arrays de critérios de verificação

O que desencadeia transições de estado

Como verificar o status de verificação

Campos do perfil de verificação — clientes pessoas físicas

Campos do perfil de verificação — clientes empresariais

Tratamento de clientes rejeitados

Guias relacionados