Atualização na verificação de clientes pessoa física: origem dos fundos agora obrigatória

A partir de 19 de outubro, clientes pessoa física criados pela Sphere precisarão informar a origem dos fundos antes que a verificação possa prosseguir.

Esta mudança alinha nossos requisitos de onboarding aos padrões de compliance dos nossos parceiros bancários. As revisões deles incluem rotineiramente verificações da origem dos fundos. Sem essa informação registrada, cada verificação se transforma em uma solicitação ao seu cliente, pausando a ativação e os pagamentos enquanto ele responde. Coletar a informação no onboarding elimina esse atrito para a grande maioria dos clientes.

Esses campos já estão disponíveis hoje. Comece a enviá-los agora para que sua integração esteja pronta antes de a mudança entrar em vigor.

O que está mudando

Pessoas físicas (KYC)

Os itens a seguir passam a ser obrigatórios no perfil de verificação do cliente. Todos são enviados em personalInformation no POST /v2/customer, exceto o documento, que é enviado separadamente.

• Origem dos fundos: personalInformation.sourceOfFunds
• Ocupação: personalInformation.occupationSocCode
• Situação profissional: personalInformation.employmentStatus
• Volume mensal esperado de pagamentos: personalInformation.expectedMonthlyPayments
• Atua em nome de outra pessoa: personalInformation.actingAsIntermediary
• Finalidade da conta: personalInformation.accountPurpose (já obrigatória hoje para clientes do EEE; passa a ser obrigatória para todos)
• Documento comprobatório, como um extrato bancário: source_of_funds_document via POST /v2/document

Empresas (KYB)

• Nenhuma mudança. primarySourceOfFunds e primarySourceOfFundsDescription já são obrigatórios na criação; nenhum requisito de documento é adicionado.

Quem é afetado

• A partir de 19 de outubro, clientes criados sem esses campos continuam sendo criados. O POST /v2/customer não rejeita a solicitação. Os itens ausentes aparecem em verificationProfiles[].criteria.required no GET /v2/customer/{id}, o perfil permanece incompleto e a verificação só é enviada quando eles forem fornecidos.
• Clientes existentes não são afetados na transição. Clientes sem essa informação registrada ainda podem receber uma solicitação do nosso parceiro bancário à medida que realizam transações; essas solicitações continuam sendo tratadas pelo seu contato na Sphere, como acontece hoje.

Cronograma‍

• Agora: todos os campos e o tipo de documento são aceitos e opcionais. Comece a enviá-los hoje.
• 19 de outubro de 2026: a exigência passa a valer para a criação de novos clientes.

O que você precisa implementar

1. Atualize seu fluxo de onboarding para coletar, para pessoas físicas: origem dos fundos, ocupação (código SOC), situação profissional, pagamentos mensais esperados, finalidade da conta e se o cliente atua como intermediário. Para empresas: seleção da origem dos fundos mais descrição (já obrigatórias).
2. Colete um documento comprobatório (extrato bancário ou equivalente) e envie-o pelo endpoint de documentos com documentType: "source_of_funds_document".
3. Se você valida valores de enum no lado do cliente, atualize-os de acordo com as listas na seção de API abaixo.
4. Confira os nomes dos campos com atenção: o POST /v2/customer ignora silenciosamente nomes de propriedades desconhecidos (sem erro), então um campo com erro de digitação não será sinalizado.

Dúvidas sobre a mudança ou sobre sua integração? Escreva para support@spherepay.co ou fale com seu gerente de conta na Sphere.

Impacto na API

Criação de clientes (POST /v2/customer): solicitações sem os novos campos são aceitas (200/201) antes e depois de 19 de outubro — os campos são opcionais no schema da solicitação. Solicitações com um valor inválido (por exemplo, sourceOfFunds: "other") retornam 422 com erros por campo no padrão RFC 9457, hoje e depois de 19 de outubro. Nomes de propriedades desconhecidos são removidos silenciosamente, não rejeitados.

Perfil de verificação: no GET /v2/customer/{id}, cada entrada em verificationProfiles[] tem name, status (incomplete | pending | approved | rejected | resubmission_required) e criteria com quatro arrays: required, pending, complete, errors. Até o envio, os novos itens aparecem em criteria.required. Um source_of_funds_document enviado aparece em criteria.pending até ser revisado pelo nosso provedor de verificação e, depois, em criteria.complete.

Envio de documentos (POST /v2/document): documentType: "source_of_funds_document", target: "customer". Formatos aceitos: PDF, JPEG, PNG. Tamanho do arquivo de 10 KB a 8 MB.

Onboarding hospedado: se você usa o onboarding hospedado da Sphere, nenhuma mudança é necessária. Os clientes são solicitados a fornecer as novas informações automaticamente.

Exemplo: criar um cliente pessoa física (após 19 de outubro)

Nome e data de nascimento ficam no nível superior; todos os campos de origem dos fundos ficam em personalInformation.

{
 "type": "individual",
 "email": "jane.smith@example.com",
 "phone": "+14155550123",
 "firstName": "Jane",
 "lastName": "Smith",
 "dateOfBirth": "1990-01-15",
 "address": { "line1": "123 Main St", "city": "Chicago", "state": "IL", "postalCode": "60601", "country": "USA" },
 "personalInformation": {
   "sourceOfFunds": "salary",
   "occupationSocCode": "151252",
   "employmentStatus": "employed",
   "expectedMonthlyPayments": "5000_9999",
   "actingAsIntermediary": false,
   "accountPurpose": "receive_salary"
 }
}


Exemplo: enviar o documento

curl -X POST "https://api.spherepay.co/v2/document" \
 -H "Authorization: Bearer <API_KEY>" \
 -F "target=customer" \
 -F "targetId=customer_abc123" \
 -F "documentType=source_of_funds_document" \
 -F "file=@bank_statement.pdf" \
 -F "description=Bank statement, last 3 months"

Formatos aceitos: PDF, JPEG, PNG, de 10 KB a 8 MB. description é opcional.

Exemplo: perfil de verificação antes e depois do envio

Os nomes dos campos de verificação estão em snake_case e diferem dos nomes dos campos da solicitação.

Antes do envio (a partir de 19 de outubro):

"verificationProfiles": [{
 "name": "kyc_profile_a",
 "status": "incomplete",
 "criteria": {
   "required": ["source_of_funds", "occupation_soc_code", "employment_status", "expected_monthly_payments", "acting_as_intermediary", "account_purpose", "source_of_funds_document"],
   "pending": [],
   "complete": ["identity_document"],
   "errors": []
 }
}]


Depois que os campos são enviados e o documento é carregado:

"verificationProfiles": [{
 "name": "kyc_profile_a",
 "status": "pending",
 "criteria": {
   "required": [],
   "pending": ["source_of_funds_document"],
   "complete": ["identity_document", "source_of_funds", "occupation_soc_code", "employment_status", "expected_monthly_payments", "acting_as_intermediary", "account_purpose"],
   "errors": []
 }
}]


Valores aceitos

sourceOfFunds para pessoas físicas (12 valores):

company_funds, ecommerce_reseller, gambling_proceeds, gifts, government_benefits, inheritance, investments_loans, pension_retirement, salary, sale_of_assets_real_estate, savings, someone_elses_funds

Três valores legados ainda são aceitos e reescritos no recebimento: gift → gifts, business_income → company_funds, investment_returns → investments_loans. other é rejeitado com 422 (sourceOfFunds must be a supported source of funds).

primarySourceOfFunds para empresas

business_loans, grants, inter_company_funds, investment_proceeds, legal_settlement, owners_capital, pension_retirement, sale_of_assets, sales_of_goods_and_services, third_party_funds, treasury_reserves