Perfiles de Verificación

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.

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

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.

La selección de perfiles aplica a los clientes que incorporas a través de la API. Los clientes incorporados mediante enlaces KYC alojados 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.

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

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

{
  "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"
}

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

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	✓	—	—

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	✓	✓	✓

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+ 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 con el customerId y el nombre del perfil.

Guías relacionadas

Seleccionar perfiles

Cómo funciona enabledVerificationProfiles y qué devuelve la API.

Incorporar un cliente con perfiles

Elige perfiles al crear y agrega uno a un cliente existente.

Eliminar un perfil

Quita un perfil que el cliente ya no necesita.

KYC individual

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

Incorporación

Transferencias

Automatización

Webhooks

Datos de referencia

Operacional

Perfiles de Verificación

Perfiles disponibles

Estados de verificación

Ciclo de vida del estado

Arreglos de criterios de verificación

Cómo consultar el estado de verificación

Eventos de webhook

Requisitos por perfil

Manejo de clientes rechazados

Guías relacionadas

Seleccionar perfiles

Incorporar un cliente con perfiles

Eliminar un perfil

KYC individual

​Perfiles disponibles

​Estados de verificación

​Ciclo de vida del estado

​Arreglos de criterios de verificación

​Cómo consultar el estado de verificación

​Eventos de webhook

​Requisitos por perfil

​Manejo de clientes rechazados

​Guías relacionadas

Seleccionar perfiles

Incorporar un cliente con perfiles

Eliminar un perfil

KYC individual

Perfiles disponibles

Estados de verificación

Ciclo de vida del estado

Arreglos de criterios de verificación

Cómo consultar el estado de verificación

Eventos de webhook

Requisitos por perfil

Manejo de clientes rechazados

Guías relacionadas