> ## 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.
# Perfil de Verificación y Estados del Cliente
> El perfil de verificación rastrea el estado KYC o KYB de un cliente. Aprende qué significa cada estado y qué activa las transiciones.
Un perfil de verificación es un registro de los requisitos que SpherePay necesita para aprobar a un cliente — individual o empresarial — antes de que pueda iniciar o recibir transferencias. Se devuelve como parte del arreglo `verificationProfiles` cada vez que llamas a `GET /v2/customer/{id}`. Monitorear el perfil de verificación es la forma principal de determinar si un cliente está listo para transferir.
La mayoría de las integraciones verán un único perfil en el arreglo `verificationProfiles`. Un cliente está listo para transferir cuando el `status` de ese perfil alcanza `approved`. Si ves nombres de perfil inesperados, contacta a tu representante de SpherePay.
Diferentes perfiles de verificación desbloquean diferentes capacidades de transferencia. Por ejemplo, las transferencias USD/EUR usan `kyc_profile_a`, mientras que las transferencias BRL/PIX requieren `kyc_profile_b` — un camino de incorporación separado. Contacta a tu representante de SpherePay para entender qué perfiles aplican a tu integración.
## Estados de verificación
El campo `status` en un perfil de verificación tiene cuatro valores posibles.
| Estado | Descripción | ¿Puede iniciar transferencias? |
| ------------ | ------------------------------------------------------------------------------------------------ | ------------------------------ |
| `incomplete` | El cliente aún no ha completado todos los requisitos de verificación. Este es el estado inicial. | No |
| `pending` | El cliente ha completado todos los requisitos y está esperando la revisión de SpherePay. | No |
| `approved` | SpherePay ha aprobado al cliente. Está completamente incorporado y puede iniciar transferencias. | Sí |
| `rejected` | SpherePay no pudo aprobar al cliente basándose en la información enviada. | No |
## Ciclo de vida del estado
Un perfil de verificación avanza por los estados en el siguiente orden:
```
incomplete → pending → approved
↘
rejected
```
* El cliente comienza en `incomplete`. El arreglo `criteria.required` lista todos los requisitos pendientes.
* Una vez que se cumplen todos los requisitos, SpherePay procesa automáticamente la verificación y mueve el perfil a `pending`. No se necesita ninguna llamada de envío.
* SpherePay completa la revisión y transiciona el perfil a `approved` o `rejected`.
## Arreglos de criterios de verificación
Cada perfil de verificación contiene un objeto `criteria` con cuatro arreglos que describen el estado actual de cada requisito.
| Arreglo | Descripción |
| ---------- | ------------------------------------------------------------------------------------------------ |
| `complete` | Requisitos que han sido cumplidos. No se necesita ninguna acción adicional. |
| `pending` | Requisitos que están siendo procesados actualmente por SpherePay. Espera a que esto se resuelva. |
| `required` | Requisitos que aún deben completarse. Tú o tu cliente deben actuar sobre estos. |
| `errors` | Requisitos con errores de validación. Corrígelos antes de volver a enviar. |
Cuando `required` está vacío y `status` es `approved`, el cliente está completamente incorporado.
## Qué desencadena las transiciones de estado
| Acción | Efecto |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Creación del cliente con correo electrónico, teléfono y dirección | Completa `complete` para `email_address`, `phone_number`, `residential_address` |
| Carga de documento de identidad | Mueve `identity_document` de `required` a `pending`, luego a `complete` después del procesamiento |
| Carga de informe de vivacidad o finalización de verificación de vivacidad facial | Cumple el requisito `liveness_report_document` o `liveness_check` |
| Aceptación de TOS vía enlace alojado | Cumple el requisito `terms_of_service` |
| Todos los elementos de `required` resueltos | SpherePay envía automáticamente para revisión; el estado se mueve a `pending` |
| Revisión manual completada por SpherePay | El estado se mueve a `approved` o `rejected` |
## Cómo verificar el estado de verificación
Llama a `GET /v2/customer/{id}` para recuperar el estado actual del perfil de verificación de un cliente.
```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"
}
```
Consulta `GET /v2/customer/{id}` para detectar cuándo ocurre la aprobación, luego procede con el registro de métodos de pago y la configuración de transferencias.
## Campos del perfil de verificación — clientes individuales
Cada elemento en los arreglos `criteria` corresponde a un requisito específico. La tabla a continuación describe cada campo y qué acción lo resuelve.
| Elemento | Acción requerida |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email_address` | Proporciona una dirección de correo electrónico al crear o actualizar el cliente |
| `phone_number` | Proporciona un número de teléfono al crear o actualizar el cliente |
| `residential_address` | Proporciona una dirección residencial completa al crear o actualizar el cliente |
| `tax_identification_number` | Proporciona un ID fiscal vía `personalInformation.taxIdentificationNumber` |
| `identity_document` | Carga un ID emitido por el gobierno vía `POST /v2/document` |
| `liveness_report_document` | Carga un informe de vivacidad de tu proveedor KYC vía `POST /v2/document` |
| `liveness_check` | Completa la verificación de vivacidad facial vía el enlace de `POST /v2/enhanced-due-diligence/face-verification-link` — mejorado, solo requerido para algunas integraciones |
| `terms_of_service` | Acepta TOS vía el enlace alojado de `POST /v2/customer/{id}/tos-link` — mejorado, solo requerido para algunas integraciones |
| `email_verification` | Verifica el correo electrónico vía los endpoints de envío y verificación OTP — mejorado, solo requerido para algunas integraciones |
| `phone_verification` | Verifica el teléfono vía los endpoints de envío y verificación OTP — mejorado, solo requerido para algunas integraciones |
## Campos del perfil de verificación — clientes empresariales
| Elemento | Acción requerida |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `email_address` | Proporciona una dirección de correo electrónico al crear o actualizar el cliente |
| `phone_number` | Proporciona un número de teléfono al crear o actualizar el cliente |
| `operating_address` | Proporciona una dirección operativa en el arreglo `addresses` |
| `registered_address` | Proporciona una dirección registrada en el arreglo `addresses` |
| `legal_name` | Proporciona `businessInformation.legalName` |
| `trade_name` | Proporciona `businessInformation.tradeName` |
| `entity_type` | Proporciona `businessInformation.entityType` |
| `description` | Proporciona `businessInformation.description` |
| `naics_code` | Proporciona `businessInformation.naicsCode` |
| `website` | Proporciona `businessInformation.website` |
| `incorporated_on` | Proporciona `businessInformation.incorporatedOn` |
| `identification_number` | Proporciona `businessInformation.identificationNumber` — los tipos varían por país |
| `estimated_annual_revenue` | Proporciona `businessInformation.estimatedAnnualRevenueInUsd` |
| `expected_monthly_payments` | Proporciona `businessInformation.expectedMonthlyPaymentsInUsd` |
| `account_purpose` | Proporciona `businessInformation.accountPurpose` |
| `source_of_funds` | Proporciona `businessInformation.primarySourceOfFunds` |
| `regulated_activities` | Proporciona `businessInformation.regulatedActivities` |
| `business_representatives` | Registra y verifica todos los UBOs vía `POST /v2/business-representative` |
| `incorporation_cert_document` | Carga vía `POST /v2/document` con `documentType: "incorporation_certificate"` |
| `shareholder_registry_document` | Carga vía `POST /v2/document` con `documentType: "shareholder_registry"` |
| `proof_of_address_document` | Carga vía `POST /v2/document` con `documentType: "proof_of_address"` |
| `terms_of_service` | Acepta TOS vía enlace alojado — mejorado, solo requerido para algunas integraciones |
| `master_service_agreement` | Firma el MSA vía el formulario alojado presentado después de la aceptación de TOS — mejorado, solo requerido para algunas integraciones |
## Manejo de clientes rechazados
Un estado `rejected` significa que la verificación no pudo aprobarse basándose en la información enviada. Los clientes con un perfil `rejected` no pueden iniciar ni recibir transferencias.
Si un cliente es rechazado incorrectamente o requiere una nueva revisión, contacta a [support@spherepay.co](mailto:support@spherepay.co) con el `customerId`.
***
## Guías relacionadas
Guía paso a paso para incorporar clientes individuales vía API.
Guía paso a paso para incorporar clientes empresariales vía API.
Incorpora clientes usando la experiencia de verificación alojada de SpherePay.
Descripción general de tipos de clientes, modelos de incorporación y métodos de integración.