Actualización en la verificación de clientes personas físicas: el origen de los fondos ahora es obligatorio

A partir del 19 de octubre, los clientes personas físicas creados a través de Sphere deberán proporcionar información sobre el origen de sus fondos antes de que la verificación pueda continuar.

Este cambio alinea nuestros requisitos de onboarding con los estándares de compliance de nuestros socios bancarios. Sus revisiones incluyen habitualmente controles del origen de los fondos. Sin esa información registrada, cada control se convierte en una solicitud a tu cliente, lo que pausa la activación y los pagos mientras responde. Recopilar la información durante el onboarding elimina esa fricción para la gran mayoría de los clientes.

Estos campos ya están disponibles hoy. Empieza a enviarlos ahora para que tu integración esté lista antes de que el cambio entre en vigor.

Qué está cambiando

Personas físicas (KYC)

Los siguientes elementos pasan a ser obligatorios en el perfil de verificación del cliente. Todos se envían en personalInformation en POST /v2/customer, excepto el documento, que se carga por separado.

• Origen de los fondos: personalInformation.sourceOfFunds
• Ocupación: personalInformation.occupationSocCode
• Situación laboral: personalInformation.employmentStatus
• Volumen mensual esperado de pagos: personalInformation.expectedMonthlyPayments
• Actúa en nombre de otra persona: personalInformation.actingAsIntermediary
• Propósito de la cuenta: personalInformation.accountPurpose (ya es obligatorio hoy para clientes del EEE; pasa a ser obligatorio para todos)
• Documento de respaldo, como un estado de cuenta bancario: source_of_funds_document mediante POST /v2/document

Empresas (KYB)

• Sin cambios. primarySourceOfFunds y primarySourceOfFundsDescription ya son obligatorios al crear el cliente; no se agrega ningún requisito de documento.

A quién afecta

• A partir del 19 de octubre, los clientes creados sin estos campos se siguen creando. POST /v2/customer no rechaza la solicitud. Los elementos faltantes aparecen en verificationProfiles[].criteria.required en GET /v2/customer/{id}, el perfil queda incompleto y la verificación no se envía hasta que se proporcionen.
• Los clientes existentes no se ven afectados en la transición. Los clientes sin esta información registrada aún pueden recibir una solicitud de nuestro socio bancario a medida que realizan transacciones; esas solicitudes se siguen gestionando a través de tu contacto en Sphere, como hoy.

Cronograma‍

• Ahora: todos los campos y el tipo de documento se aceptan y son opcionales. Empieza a enviarlos hoy.
• 19 de octubre de 2026: la exigencia entra en vigor para la creación de nuevos clientes.

Qué necesitas implementar

1. Actualiza tu flujo de onboarding para recopilar, en el caso de personas físicas: origen de los fondos, ocupación (código SOC), situación laboral, pagos mensuales esperados, propósito de la cuenta y si el cliente actúa como intermediario. Para empresas: selección del origen de los fondos más una descripción (ya obligatorios).
2. Recopila un documento de respaldo (estado de cuenta bancario o equivalente) y cárgalo mediante el endpoint de documentos con documentType: "source_of_funds_document".
3. Si validas valores de enum del lado del cliente, actualízalos según las listas de la sección de API más abajo.
4. Revisa con cuidado los nombres de los campos: POST /v2/customer ignora en silencio los nombres de propiedades desconocidos (sin error), por lo que un campo mal escrito no se marcará.

¿Tienes preguntas sobre el cambio o tu integración? Escribe a support@spherepay.co o comunícate con tu gerente de cuenta en Sphere.

Impacto en la API

Creación de clientes (POST /v2/customer): las solicitudes sin los nuevos campos se aceptan (200/201) antes y después del 19 de octubre; los campos son opcionales en el esquema de la solicitud. Las solicitudes con un valor inválido (por ejemplo, sourceOfFunds: "other") devuelven 422 con errores por campo según RFC 9457, hoy y después del 19 de octubre. Los nombres de propiedades desconocidos se eliminan en silencio, no se rechazan.

Perfil de verificación: en GET /v2/customer/{id}, cada entrada de verificationProfiles[] tiene name, status (incomplete | pending | approved | rejected | resubmission_required) y criteria con cuatro arrays: required, pending, complete, errors. Hasta el envío, los nuevos elementos aparecen en criteria.required. Un source_of_funds_document cargado aparece en criteria.pending hasta que nuestro proveedor de verificación lo revisa y, luego, en criteria.complete.

Carga de documentos (POST /v2/document): documentType: "source_of_funds_document", target: "customer". Formatos aceptados: PDF, JPEG, PNG. Tamaño del archivo de 10 KB a 8 MB.

Onboarding alojado: si usas el onboarding alojado de Sphere, no se requiere ningún cambio. A los clientes se les solicita la nueva información automáticamente.

Ejemplo: crear un cliente persona física (después del 19 de octubre)

El nombre y la fecha de nacimiento van en el nivel superior; todos los campos del origen de los fondos van en 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"
 }
}


Ejemplo: cargar el 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 aceptados: PDF, JPEG, PNG, de 10 KB a 8 MB. description es opcional.

Ejemplo: perfil de verificación antes y después del envío

Los nombres de los campos de verificación están en snake_case y difieren de los nombres de los campos de la solicitud.

Antes del envío (desde el 19 de octubre):

"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": []
 }
}]


Después de enviar los campos y cargar el documento:

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

sourceOfFunds para personas 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

Tres valores heredados todavía se aceptan y se reescriben al recibirse: gift → gifts, business_income → company_funds, investment_returns → investments_loans. other se rechaza con 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