> ## 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.

# Perfiles de Verificación

> Un perfil de verificación rastrea el estado de aprobación KYC o KYB de un cliente para un grupo de productos. Conoce qué perfiles existen, qué requiere y desbloquea cada uno, y cómo cambian los estados.

Un perfil de verificación es el conjunto de requisitos KYC o KYB que SpherePay necesita para aprobar a un cliente (`customer`) — individual o empresarial — para un grupo de productos. Cada perfil desbloquea sus propios productos y activos. Un cliente puede tener varios perfiles a la vez, y cada uno avanza por sus propios estados de forma independiente.

Los perfiles se devuelven en el arreglo `verificationProfiles` de `GET /v2/customer/{id}`. Monitorearlos es la forma principal de determinar si un cliente está listo para transferir en un riel determinado.

## Perfiles disponibles

SpherePay habilita un conjunto de perfiles para tu aplicación. Cada cliente se evalúa contra los perfiles que selecciones para él con `enabledVerificationProfiles` — consulta [Seleccionar perfiles](https://docs.spherepay.co/es/concepts/onboarding/verification-profiles/eligibility.md).

| Perfil | Nombre en la API | Productos | Rieles | Activos | Residentes elegibles | Limitaciones |
| - | - | - | - | - | - | - |
| A | `kyc_profile_a` (individuales), `kyb_profile_a` (empresas), `ubo_kyc_profile_a` (representantes de empresa) | Transferencias, offloader wallets, cuentas on-ramper | ACH, Wire, SEPA, redes de stablecoins | USD, EUR, USDC, USDT, EURC | Residentes de EE. UU. y de fuera de EE. UU. | — |
| C | `kyc_profile_c`, `kyb_profile_c`, `ubo_kyc_profile_c` | Transferencias | Wire, SWIFT, Ethereum, Solana, Tron | USD, USDC, USDT | Solo residentes fuera de EE. UU. | Solo off-ramp |
| D | `kyc_profile_d`, `kyb_profile_d`, `ubo_kyc_profile_d` | Transferencias | SPEI | MXN | Solo residentes fuera de EE. UU. | Solo MXN a USD; requiere el perfil C en el mismo cliente |

> [!NOTE]
>
> Cuando SpherePay habilita un nuevo perfil para tu aplicación, los clientes existentes **no** se inscriben automáticamente. Verificar a un cliente para un perfil adicional tiene un costo, así que agregas el perfil de forma explícita con `PATCH /v2/customer/{id}`. Consulta [Agregar un perfil a un cliente existente](https://docs.spherepay.co/es/concepts/onboarding/verification-profiles/onboard-new-customer.md#agregar-un-perfil-más-tarde).

> [!NOTE]
>
> La selección de perfiles aplica a los clientes que incorporas a través de la API. Los clientes incorporados mediante [enlaces KYC alojados](https://docs.spherepay.co/es/concepts/onboarding/kyc-via-link.md) se inscriben en los perfiles predeterminados de tu aplicación; `enabledVerificationProfiles` no está disponible en el flujo alojado.

## Estados de verificación

El campo `status` en un perfil de verificación tiene cinco valores posibles.

| Estado | Descripción | ¿Puede operar con este perfil? |
| - | - | - |
| `incomplete` | No se han proporcionado todos los requisitos. Este es el estado inicial. `criteria.required` lista lo que falta. | No |
| `pending` | Todos los requisitos están completos y SpherePay está revisando. | No |
| `approved` | SpherePay aprobó al cliente para este perfil. | Sí |
| `rejected` | SpherePay no pudo aprobar al cliente con la información enviada. | No |
| `resubmission_required` | SpherePay necesita información corregida. `criteria.errors` lista qué corregir. | No |

## Ciclo de vida del estado

```
incomplete → pending → approved
                    ↘ rejected
                    ↘ resubmission_required → pending
```

* El cliente comienza en `incomplete`. El arreglo `criteria.required` lista todos los requisitos pendientes de ese perfil.
* Una vez que se cumple cada requisito, SpherePay envía al cliente a revisión y el perfil pasa a `pending`. No se necesita ninguna llamada de envío.
* La revisión se completa y el perfil pasa a `approved`, `rejected` o `resubmission_required`.
* Cada perfil avanza por su cuenta. El perfil C puede alcanzar `approved` mientras el perfil A sigue en `pending` en el mismo cliente.

> [!WARNING]
>
> Un cliente se envía a revisión solo cuando **todos** los perfiles habilitados tienen `criteria.required` vacío. Si habilitas dos perfiles, proporciona los requisitos de ambos antes de esperar que alguno salga de `incomplete`.

## Arreglos de criterios de verificación

Cada perfil de verificación contiene un objeto `criteria` con cuatro arreglos.

| Arreglo | Descripción |
| - | - |
| `complete` | Requisitos que han sido cumplidos. No se necesita ninguna acción adicional. |
| `pending` | Requisitos que se están procesando actualmente. 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, como objetos `{ name, detail }`. Corrígelos antes de volver a enviar. |

Los requisitos compartidos entre perfiles se satisfacen una sola vez para todos ellos. Si un cliente ya tiene un perfil A aprobado, agregar el perfil C solo solicita los criterios que C necesita y A no.

## Cómo consultar el estado de verificación

```bash theme={"dark"}
GET https://api.spherepay.co/v2/customer/{id}
```

```json theme={"dark"}
{
  "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"
}
```

> [!TIP]
>
> Consulta `GET /v2/customer/{id}` periódicamente para detectar cuándo un perfil alcanza `approved`, y luego continúa con el registro de métodos de pago y las transferencias en los rieles que ese perfil desbloquea.

## Eventos de webhook

En lugar de consultar periódicamente, suscríbete a los [eventos de webhook de clientes](https://docs.spherepay.co/es/concepts/webhooks/event-catalog.md). SpherePay emite un evento por perfil de verificación por cambio de estado — `customer.pending`, `customer.approved` y `customer.rejected` — y `data.verificationProfile` nombra el perfil que cambió, por ejemplo `kyc_profile_c` o `ubo_kyc_profile_a`. Un cliente con dos perfiles produce dos flujos de eventos independientes, así que basa tu manejo en el nombre del perfil y no solo en el ID del cliente.

## Requisitos por perfil

Cada perfil evalúa su propio conjunto de criterios. Expande un tipo de cliente para ver qué perfiles evalúan cada elemento y cómo satisfacerlo.

> [accordion] Clientes individuales
>
> Cada elemento en los arreglos `criteria` corresponde a un requisito. Las columnas muestran qué perfiles lo evalúan.
>
> | Elemento | Acción requerida | A | C | D |
> | - | - | - | - | - |
> | `email_address` | Proporciona `email` | ✓ | ✓ | ✓ |
> | `phone_number` | Proporciona `phone` | ✓ | ✓ | ✓ |
> | `residential_address` | Proporciona el objeto `address` completo | ✓ | ✓ | ✓ |
> | `tax_identification_number` | Proporciona `personalInformation.taxIdentificationNumber` con su tipo y país | ✓ | ✓ | ✓ |
> | `identity_document` | Sube una identificación oficial vía `POST /v2/document` (`passport`, `id_card` frente y reverso, o `drivers`) | ✓ | ✓ | ✓ |
> | `liveness_report_document` | Sube un reporte de prueba de vida vía `POST /v2/document` con `documentType: "liveness_report_document"` | ✓ | ✓ | ✓ |
> | `source_of_funds_document` | Sube vía `POST /v2/document` con `documentType: "source_of_funds_document"` | ✓ | ✓ | ✓ |
> | `source_of_funds` | Proporciona `personalInformation.sourceOfFunds` | ✓ | ✓ | ✓ |
> | `occupation_soc_code` | Proporciona `personalInformation.occupationSocCode` | ✓ | ✓ | ✓ |
> | `account_purpose` | Proporciona `personalInformation.accountPurpose` (y `accountPurposeDescription` cuando el propósito es `other`) | ✓ | — | — |
> | `employment_status` | Proporciona `personalInformation.employmentStatus` | ✓ | — | — |
> | `acting_as_intermediary` | Proporciona `personalInformation.actingAsIntermediary` | ✓ | — | — |
> | `expected_monthly_payments` | Proporciona `personalInformation.expectedMonthlyPayments` | ✓ | — | ✓ |
> | `country_of_birth` | Proporciona `personalInformation.countryOfBirth` (ISO 3166-1 alfa-3) | Solo residentes EEA+ | ✓ | ✓ |
> | `nationality` | Proporciona `personalInformation.nationality` (ISO 3166-1 alfa-3) | Solo residentes EEA+ | ✓ | ✓ |
> | `sex` | Proporciona `personalInformation.gender` | — | ✓ | ✓ |
> | `proof_of_address_document` | Sube vía `POST /v2/document` con `documentType: "proof_of_address_document"` | — | ✓ | ✓ |
> | `w8_ben_document` | Sube vía `POST /v2/document` con `documentType: "w8_ben_document"` | — | ✓ | ✓ |
> | `state_of_birth` | Proporciona `personalInformation.stateOfBirth` | — | — | ✓ |
> | `expected_monthly_transaction_count`, `transaction_frequency`, `expected_counterparty_types`, `expected_geographies` | Proporciona `personalExpectedActivity` | — | — | ✓ |
> | `ip_address`, `ip_address_approved` | Proporciona `ipAddress` (la IP de registro del cliente). `ip_address_approved` lo resuelve SpherePay a partir de la geolocalización de la dirección. | — | — | ✓ |
> | `terms_of_service` | Acepta los términos de servicio vía el enlace alojado de `POST /v2/customer/{id}/tos-link` — solo cuando los TOS están habilitados para tu aplicación | ✓ | ✓ | ✓ |
> | `liveness_check`, `email_verification`, `phone_verification` | Verificaciones mejoradas vía el enlace de verificación facial y los endpoints OTP — solo requeridas para algunas integraciones | ✓ | — | — |

> [accordion] Clientes empresariales
>
> | Elemento | Acción requerida | A | C | D |
> | - | - | - | - | - |
> | `email_address`, `phone_number` | Proporciona `email` y `phone` | ✓ | ✓ | ✓ |
> | `operating_address`, `registered_address` | Proporciona ambas entradas en el arreglo `addresses` | ✓ | ✓ | ✓ |
> | `legal_name`, `trade_name`, `entity_type`, `description`, `website`, `incorporated_on`, `naics_code` | Proporciona los campos correspondientes de `businessInformation` | ✓ | ✓ | ✓ |
> | `identification_number` | Proporciona `businessInformation.identificationNumber` e `identificationNumberType` | ✓ | ✓ | ✓ |
> | `estimated_annual_revenue`, `expected_monthly_payments`, `account_purpose` | Proporciona `estimatedAnnualRevenueInUsd`, `expectedMonthlyPaymentsInUsd`, `accountPurpose` | ✓ | ✓ | ✓ |
> | `source_of_funds`, `source_of_funds_description` | Proporciona `primarySourceOfFunds` y `primarySourceOfFundsDescription` | ✓ | ✓ | ✓ |
> | `is_dao`, `regulated_activities`, `participates_in_regulated_financial_activity`, `operates_in_prohibited_countries` | Proporciona los campos correspondientes de `businessInformation` | ✓ | ✓ | ✓ |
> | `business_representatives`, `control_person_added` | Registra personas asociadas vía `POST /v2/business-representative`. Para empresas EEA+ esto incluye directores, firmantes, personas de control y propietarios ≥ 25%; en caso contrario, propietarios con ≥ 25% y una persona de control | ✓ | ✓ | ✓ |
> | `eea_control_person_present` | Registra al menos un representante con `isControlPerson: true` | Solo empresas EEA+ | — | — |
> | `eea_ap_kyc_scope` | Al menos un director registrado, y cada director, firmante, persona de control y propietario ≥ 25% completa la verificación de identidad completa | Solo empresas EEA+ | — | — |
> | `incorporation_cert_document`, `shareholder_registry_document`, `proof_of_address_document` | Sube vía `POST /v2/document` con el `documentType` correspondiente | ✓ | ✓ | ✓ |
> | `registration_number` | Proporciona `businessInformation.registrationNumber` y `registrationNumberType` | Solo empresas EEA+ | ✓ | ✓ |
> | `incorporation_articles_document`, `w8_ben_e_document`, `bank_statement_document`, `source_of_funds_document`, `corporate_resolution_document`, `financial_statements_document` | Sube vía `POST /v2/document` con el `documentType` correspondiente | — | ✓ | ✓ |
> | `expected_monthly_transaction_count`, `transaction_frequency`, `expected_counterparty_types`, `expected_geographies` | Proporciona `businessExpectedActivity` | — | — | ✓ |
> | `ip_address`, `ip_address_approved` | Proporciona `ipAddress` | — | — | ✓ |
> | `terms_of_service` | Acepta los términos de servicio vía enlace alojado — solo cuando los TOS están habilitados para tu aplicación | ✓ | ✓ | ✓ |

> [accordion] Representantes de empresa
>
> Cada representante tiene su propia entrada `ubo_kyc_profile_*`, devuelta en `GET /v2/business-representative/{id}`. Los documentos de un representante se suben con `target="business-representative"`.
>
> | Elemento | Acción requerida | A | C | D |
> | - | - | - | - | - |
> | `email_address`, `phone_number` | Proporciona `email` y `phone` | ✓ | ✓ | ✓ |
> | `residential_address` | Proporciona el objeto `address` completo | ✓ | ✓ | ✓ |
> | `tax_identification_number` | Proporciona `personalInformation.taxIdentificationNumber` con su tipo y país | ✓ | ✓ | ✓ |
> | `ownership_percentage`, `is_control_person`, `is_signer`, `relationship_established_at`, `title` | Proporciona `representationDetails` | ✓ | ✓ | ✓ |
> | `identity_document`, `liveness_report_document`, `proof_of_address_document` | Sube vía `POST /v2/document` con `target="business-representative"` | ✓ | ✓ | ✓ |
> | `country_of_birth`, `nationality` | Proporciona `personalInformation.countryOfBirth` y `nationality` (ISO 3166-1 alfa-3) | Solo empresas EEA+ | ✓ | ✓ |
> | `middle_name`, `sex` | Proporciona `middleName` y `personalInformation.gender` — se validan al crear el representante | — | ✓ | ✓ |
> | `occupation_soc_code`, `source_of_funds` | Proporciona `personalInformation.occupationSocCode` y `sourceOfFunds` | — | ✓ | ✓ |
> | `w8_ben_document`, `source_of_funds_document` | Sube vía `POST /v2/document` con `target="business-representative"` | — | ✓ | ✓ |
> | `state_of_birth` | Proporciona `personalInformation.stateOfBirth` | — | — | ✓ |
>
> Consulta [Empresas EEA+](https://docs.spherepay.co/es/concepts/onboarding/business-kyb.md#eea-businesses) para los requisitos completos de personas asociadas.

## Manejo de clientes rechazados

Un estado `rejected` significa que SpherePay no pudo aprobar al cliente para ese perfil. El cliente no puede operar con los productos que ese perfil desbloquea; los demás perfiles aprobados del mismo cliente no se ven afectados.

Si un cliente fue rechazado incorrectamente o requiere una nueva revisión, contacta a [support@spherepay.co](mailto:support@spherepay.co) con el `customerId` y el nombre del perfil.

***

## Guías relacionadas

> [card] [Seleccionar perfiles](https://docs.spherepay.co/es/concepts/onboarding/verification-profiles/eligibility.md)
>
> Cómo funciona `enabledVerificationProfiles` y qué devuelve la API.

> [card] [Incorporar un cliente con perfiles](https://docs.spherepay.co/es/concepts/onboarding/verification-profiles/onboard-new-customer.md)
>
> Elige perfiles al crear y agrega uno a un cliente existente.

> [card] [Eliminar un perfil](https://docs.spherepay.co/es/concepts/onboarding/verification-profiles/remove-profile.md)
>
> Quita un perfil que el cliente ya no necesita.

> [card] [KYC individual](https://docs.spherepay.co/es/concepts/onboarding/individual-kyc.md)
>
> Guía paso a paso para incorporar clientes individuales vía API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.