Perfis de Verificação

Um perfil de verificação é o conjunto de requisitos KYC ou KYB que o SpherePay precisa para aprovar um cliente (customer) — pessoa física ou jurídica — para um grupo de produtos. Cada perfil desbloqueia seus próprios produtos e ativos. Um cliente pode ter vários perfis ao mesmo tempo, e cada um avança pelos seus próprios status de forma independente. Os perfis são retornados no array verificationProfiles de GET /v2/customer/{id}. Monitorá-los é a principal forma de determinar se um cliente está pronto para transferir em um determinado rail.

Perfis disponíveis

O SpherePay habilita um conjunto de perfis para a sua aplicação. Cada cliente é avaliado contra os perfis que você seleciona para ele com enabledVerificationProfiles — veja Selecionar perfis.

Perfil	Nome na API	Produtos	Rails	Ativos	Residentes elegíveis	Limitações
A	`kyc_profile_a` (pessoas físicas), `kyb_profile_a` (empresas), `ubo_kyc_profile_a` (representantes da empresa)	Transferências, offloader wallets, contas on-ramper	ACH, Wire, SEPA, redes de stablecoins	USD, EUR, USDC, USDT, EURC	Residentes nos EUA e fora dos EUA	—
C	`kyc_profile_c`, `kyb_profile_c`, `ubo_kyc_profile_c`	Transferências	Wire, SWIFT, Ethereum, Solana, Tron	USD, USDC, USDT	Apenas residentes fora dos EUA	Apenas off-ramp
D	`kyc_profile_d`, `kyb_profile_d`, `ubo_kyc_profile_d`	Transferências	SPEI	MXN	Apenas residentes fora dos EUA	Apenas MXN para USD; exige o perfil C no mesmo cliente

Quando o SpherePay habilita um novo perfil para a sua aplicação, os clientes existentes não são inscritos automaticamente. Verificar um cliente para um perfil adicional tem um custo, então você adiciona o perfil explicitamente com PATCH /v2/customer/{id}. Veja Adicionar um perfil a um cliente existente.

A seleção de perfis se aplica aos clientes que você cadastra pela API. Clientes cadastrados por links KYC hospedados são inscritos nos perfis padrão da sua aplicação; enabledVerificationProfiles não está disponível no fluxo hospedado.

Status de verificação

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

Status	Descrição	Pode operar com este perfil?
`incomplete`	Nem todos os requisitos foram fornecidos. Este é o estado inicial. `criteria.required` lista o que está pendente.	Não
`pending`	Todos os requisitos foram fornecidos e o SpherePay está analisando.	Não
`approved`	O SpherePay aprovou o cliente para este perfil.	Sim
`rejected`	O SpherePay não pôde aprovar o cliente com base nas informações enviadas.	Não
`resubmission_required`	O SpherePay precisa de informações corrigidas. `criteria.errors` lista o que corrigir.	Não

Ciclo de vida do status

incomplete → pending → approved
                    ↘ rejected
                    ↘ resubmission_required → pending

O cliente começa em incomplete. O array criteria.required lista todos os requisitos pendentes daquele perfil.
Assim que todos os requisitos forem atendidos, o SpherePay envia o cliente para análise e o perfil passa para pending. Nenhuma chamada de submit é necessária.
A análise é concluída e o perfil passa para approved, rejected ou resubmission_required.
Cada perfil avança por conta própria. O perfil C pode chegar a approved enquanto o perfil A ainda está em pending no mesmo cliente.

Um cliente só é enviado para análise quando todos os perfis habilitados têm criteria.required vazio. Se você habilitar dois perfis, forneça os requisitos de ambos antes de esperar que algum saia de incomplete.

Arrays de critérios de verificação

Cada perfil de verificação contém um objeto criteria com quatro arrays.

Array	Descrição
`complete`	Requisitos que foram atendidos. Nenhuma ação adicional necessária.
`pending`	Requisitos que estão sendo processados no momento. Aguarde a resolução.
`required`	Requisitos que ainda precisam ser concluídos. Você ou seu cliente precisam agir sobre eles.
`errors`	Requisitos com erros de validação, como objetos `{ name, detail }`. Corrija-os antes de reenviar.

Requisitos compartilhados entre perfis são atendidos uma única vez para todos eles. Se um cliente já tem um perfil A aprovado, adicionar o perfil C só pede os critérios que C precisa e A não pediu.

Como verificar o status de verificação

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

{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "enabledVerificationProfiles": ["a", "c"],
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "approved",
      "criteria": {
        "complete": ["email_address", "phone_number", "residential_address", "tax_identification_number", "identity_document", "liveness_report_document", "account_purpose", "source_of_funds", "expected_monthly_payments", "employment_status", "acting_as_intermediary", "occupation_soc_code", "source_of_funds_document"],
        "pending": [],
        "required": [],
        "errors": []
      }
    },
    {
      "name": "kyc_profile_c",
      "status": "incomplete",
      "criteria": {
        "complete": ["email_address", "phone_number", "residential_address", "tax_identification_number", "identity_document", "liveness_report_document", "source_of_funds", "occupation_soc_code", "source_of_funds_document"],
        "pending": [],
        "required": ["sex", "country_of_birth", "nationality", "proof_of_address_document", "w8_ben_document"],
        "errors": []
      }
    }
  ],
  "type": "individual"
}

Consulte GET /v2/customer/{id} periodicamente para detectar quando um perfil chega a approved, e então prossiga com o registro de métodos de pagamento e as transferências nos rails que aquele perfil desbloqueia.

Eventos de webhook

Em vez de consultar periodicamente, assine os eventos de webhook de clientes. O SpherePay emite um evento por perfil de verificação por mudança de status — customer.pending, customer.approved e customer.rejected — e data.verificationProfile nomeia o perfil que mudou, por exemplo kyc_profile_c ou ubo_kyc_profile_a. Um cliente com dois perfis produz dois fluxos de eventos independentes, então baseie o seu tratamento no nome do perfil e não apenas no ID do cliente.

Requisitos por perfil

Cada perfil avalia o próprio conjunto de critérios. Expanda um tipo de cliente para ver quais perfis avaliam cada item e como atendê-lo.

Clientes pessoa física

Cada item nos arrays criteria corresponde a um requisito. As colunas mostram quais perfis o avaliam.

Item	Ação necessária	A	C	D
`email_address`	Forneça `email`	✓	✓	✓
`phone_number`	Forneça `phone`	✓	✓	✓
`residential_address`	Forneça o objeto `address` completo	✓	✓	✓
`tax_identification_number`	Forneça `personalInformation.taxIdentificationNumber` com seu tipo e país	✓	✓	✓
`identity_document`	Envie um documento de identidade oficial via `POST /v2/document` (`passport`, `id_card` frente e verso, ou `drivers`)	✓	✓	✓
`liveness_report_document`	Envie um relatório de prova de vida via `POST /v2/document` com `documentType: "liveness_report_document"`	✓	✓	✓
`source_of_funds_document`	Envie via `POST /v2/document` com `documentType: "source_of_funds_document"`	✓	✓	✓
`source_of_funds`	Forneça `personalInformation.sourceOfFunds`	✓	✓	✓
`occupation_soc_code`	Forneça `personalInformation.occupationSocCode`	✓	✓	✓
`account_purpose`	Forneça `personalInformation.accountPurpose` (e `accountPurposeDescription` quando a finalidade for `other`)	✓	—	—
`employment_status`	Forneça `personalInformation.employmentStatus`	✓	—	—
`acting_as_intermediary`	Forneça `personalInformation.actingAsIntermediary`	✓	—	—
`expected_monthly_payments`	Forneça `personalInformation.expectedMonthlyPayments`	✓	—	✓
`country_of_birth`	Forneça `personalInformation.countryOfBirth` (ISO 3166-1 alfa-3)	Apenas residentes EEA+	✓	✓
`nationality`	Forneça `personalInformation.nationality` (ISO 3166-1 alfa-3)	Apenas residentes EEA+	✓	✓
`sex`	Forneça `personalInformation.gender`	—	✓	✓
`proof_of_address_document`	Envie via `POST /v2/document` com `documentType: "proof_of_address_document"`	—	✓	✓
`w8_ben_document`	Envie via `POST /v2/document` com `documentType: "w8_ben_document"`	—	✓	✓
`state_of_birth`	Forneça `personalInformation.stateOfBirth`	—	—	✓
`expected_monthly_transaction_count`, `transaction_frequency`, `expected_counterparty_types`, `expected_geographies`	Forneça `personalExpectedActivity`	—	—	✓
`ip_address`, `ip_address_approved`	Forneça `ipAddress` (o IP de cadastro do cliente). `ip_address_approved` é resolvido pelo SpherePay a partir da geolocalização do endereço.	—	—	✓
`terms_of_service`	Aceite os termos de serviço via link hospedado de `POST /v2/customer/{id}/tos-link` — apenas quando os TOS estão habilitados para a sua aplicação	✓	✓	✓
`liveness_check`, `email_verification`, `phone_verification`	Verificações aprimoradas via link de verificação facial e endpoints OTP — exigidas apenas para algumas integrações	✓	—	—

Clientes pessoa jurídica

Item	Ação necessária	A	C	D
`email_address`, `phone_number`	Forneça `email` e `phone`	✓	✓	✓
`operating_address`, `registered_address`	Forneça ambas as entradas no array `addresses`	✓	✓	✓
`legal_name`, `trade_name`, `entity_type`, `description`, `website`, `incorporated_on`, `naics_code`	Forneça os campos correspondentes de `businessInformation`	✓	✓	✓
`identification_number`	Forneça `businessInformation.identificationNumber` e `identificationNumberType`	✓	✓	✓
`estimated_annual_revenue`, `expected_monthly_payments`, `account_purpose`	Forneça `estimatedAnnualRevenueInUsd`, `expectedMonthlyPaymentsInUsd`, `accountPurpose`	✓	✓	✓
`source_of_funds`, `source_of_funds_description`	Forneça `primarySourceOfFunds` e `primarySourceOfFundsDescription`	✓	✓	✓
`is_dao`, `regulated_activities`, `participates_in_regulated_financial_activity`, `operates_in_prohibited_countries`	Forneça os campos correspondentes de `businessInformation`	✓	✓	✓
`business_representatives`, `control_person_added`	Registre pessoas associadas via `POST /v2/business-representative`. Para empresas EEA+ isso inclui diretores, signatários, pessoas de controle e sócios ≥ 25%; caso contrário, sócios com ≥ 25% e uma pessoa de controle	✓	✓	✓
`eea_control_person_present`	Registre pelo menos um representante com `isControlPerson: true`	Somente empresas EEA+	—	—
`eea_ap_kyc_scope`	Pelo menos um diretor cadastrado, e cada diretor, signatário, pessoa de controle e sócio ≥ 25% conclui a verificação de identidade completa	Somente empresas EEA+	—	—
`incorporation_cert_document`, `shareholder_registry_document`, `proof_of_address_document`	Envie via `POST /v2/document` com o `documentType` correspondente	✓	✓	✓
`registration_number`	Forneça `businessInformation.registrationNumber` e `registrationNumberType`	Somente empresas EEA+	✓	✓
`incorporation_articles_document`, `w8_ben_e_document`, `bank_statement_document`, `source_of_funds_document`, `corporate_resolution_document`, `financial_statements_document`	Envie via `POST /v2/document` com o `documentType` correspondente	—	✓	✓
`expected_monthly_transaction_count`, `transaction_frequency`, `expected_counterparty_types`, `expected_geographies`	Forneça `businessExpectedActivity`	—	—	✓
`ip_address`, `ip_address_approved`	Forneça `ipAddress`	—	—	✓
`terms_of_service`	Aceite os termos de serviço via link hospedado — apenas quando os TOS estão habilitados para a sua aplicação	✓	✓	✓

Representantes da empresa

Cada representante tem a própria entrada ubo_kyc_profile_*, retornada em GET /v2/business-representative/{id}. Os documentos de um representante são enviados com target="business-representative".

Item	Ação necessária	A	C	D
`email_address`, `phone_number`	Forneça `email` e `phone`	✓	✓	✓
`residential_address`	Forneça o objeto `address` completo	✓	✓	✓
`tax_identification_number`	Forneça `personalInformation.taxIdentificationNumber` com seu tipo e país	✓	✓	✓
`ownership_percentage`, `is_control_person`, `is_signer`, `relationship_established_at`, `title`	Forneça `representationDetails`	✓	✓	✓
`identity_document`, `liveness_report_document`, `proof_of_address_document`	Envie via `POST /v2/document` com `target="business-representative"`	✓	✓	✓
`country_of_birth`, `nationality`	Forneça `personalInformation.countryOfBirth` e `nationality` (ISO 3166-1 alfa-3)	Somente empresas EEA+	✓	✓
`middle_name`, `sex`	Forneça `middleName` e `personalInformation.gender` — validados na criação do representante	—	✓	✓
`occupation_soc_code`, `source_of_funds`	Forneça `personalInformation.occupationSocCode` e `sourceOfFunds`	—	✓	✓
`w8_ben_document`, `source_of_funds_document`	Envie via `POST /v2/document` com `target="business-representative"`	—	✓	✓
`state_of_birth`	Forneça `personalInformation.stateOfBirth`	—	—	✓

Consulte Empresas EEA+ para os requisitos completos de pessoas associadas.

Tratamento de clientes rejeitados

Um status rejected significa que o SpherePay não pôde aprovar o cliente para aquele perfil. O cliente não pode operar com os produtos que aquele perfil desbloqueia; os demais perfis aprovados do mesmo cliente não são afetados. Se um cliente foi rejeitado incorretamente ou precisa de nova análise, entre em contato com support@spherepay.co informando o customerId e o nome do perfil.

Guias relacionados

Selecionar perfis

Como enabledVerificationProfiles funciona e o que a API retorna.

Cadastrar um cliente com perfis

Escolha perfis na criação e adicione um a um cliente existente.

Remover um perfil

Remova um perfil que o cliente não precisa mais.

KYC de pessoa física

Guia passo a passo para cadastrar clientes pessoa física via API.

Onboarding

Transferências

Automação

Webhooks

Dados de referência

Operacional

Perfis de Verificação

Perfis disponíveis

Status de verificação

Ciclo de vida do status

Arrays de critérios de verificação

Como verificar o status de verificação

Eventos de webhook

Requisitos por perfil

Tratamento de clientes rejeitados

Guias relacionados

Selecionar perfis

Cadastrar um cliente com perfis

Remover um perfil

KYC de pessoa física

​Perfis disponíveis

​Status de verificação

​Ciclo de vida do status

​Arrays de critérios de verificação

​Como verificar o status de verificação

​Eventos de webhook

​Requisitos por perfil

​Tratamento de clientes rejeitados

​Guias relacionados

Selecionar perfis

Cadastrar um cliente com perfis

Remover um perfil

KYC de pessoa física

Perfis disponíveis

Status de verificação

Ciclo de vida do status

Arrays de critérios de verificação

Como verificar o status de verificação

Eventos de webhook

Requisitos por perfil

Tratamento de clientes rejeitados

Guias relacionados