Perfil de Verificación y Estados del Cliente

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.

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

{
  "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 con el customerId.

Guías relacionadas

KYC Individual

Guía paso a paso para incorporar clientes individuales vía API.

KYB Empresarial

Guía paso a paso para incorporar clientes empresariales vía API.

KYC vía enlace alojado

Incorpora clientes usando la experiencia de verificación alojada de SpherePay.

Descripción general de clientes

Descripción general de tipos de clientes, modelos de incorporación y métodos de integración.

​Estados de verificación

​Ciclo de vida del estado

​Arreglos de criterios de verificación

​Qué desencadena las transiciones de estado

​Cómo verificar el estado de verificación

​Campos del perfil de verificación — clientes individuales

​Campos del perfil de verificación — clientes empresariales

​Manejo de clientes rechazados

​Guías relacionadas

KYC Individual

KYB Empresarial

KYC vía enlace alojado

Descripción general de clientes

Estados de verificación

Ciclo de vida del estado

Arreglos de criterios de verificación

Qué desencadena las transiciones de estado

Cómo verificar el estado de verificación

Campos del perfil de verificación — clientes individuales

Campos del perfil de verificación — clientes empresariales

Manejo de clientes rechazados

Guías relacionadas