Saltar al contenido principal
La integración con enlace alojado es la forma más rápida de incorporar clientes en SpherePay. En lugar de construir una UI de verificación personalizada, creas un cliente a través de la API, recuperas un enlace alojado y redirige a tu cliente para completar su verificación completa en una página gestionada por SpherePay. La experiencia alojada maneja la carga de documentos, la verificación de vivacidad facial y todas las preguntas requeridas en un único flujo. Este enfoque funciona tanto para clientes individuales (KYC) como para clientes empresariales (KYB).
Usa el enfoque de enlace alojado para el tiempo de integración más rápido. Requiere trabajo de frontend mínimo — solo gestionas la llamada API inicial y el redireccionamiento.

​
Cuándo usar este enfoque

El enlace alojado es ideal cuando:
  • Quieres integrar rápidamente sin construir una UI de incorporación personalizada
  • Prefieres delegar la carga de documentos, las verificaciones de vivacidad y el OTP a SpherePay
  • Estás prototipando o realizando un lanzamiento inicial antes de invertir en un flujo completamente personalizado
Si necesitas control completo sobre la experiencia de recopilación de datos o quieres integrar los pasos de verificación directamente dentro de tu producto, usa la integración basada en API en su lugar.
Elige un único método de integración para cada cliente. No mezcles el enlace alojado y los enfoques de API para el mismo cliente, ni recurras a uno si el otro falla — esto resultará en una incorporación fallida.

​
Cómo funciona

  1. Llamas a POST /v2/customer para crear un registro de cliente con datos de contacto básicos.
  2. Llamas al endpoint de enlace TOS en paralelo para generar un enlace de aceptación de Términos de Servicio.
  3. Llamas al endpoint de enlace KYC/KYB para generar un enlace de verificación alojado.
  4. Redireccionas o envías el enlace a tu cliente.
  5. El cliente completa todo el proceso de verificación en la página alojada.
  6. Consultas GET /v2/customer/{id} para detectar cuándo el perfil de verificación alcanza approved.

​
Guía paso a paso

1

Crear un cliente

Llama a POST /v2/customer con la información de contacto básica y la dirección del cliente. Para el camino de enlace alojado, no necesitas incluir personalInformation — el cliente ingresa esa información en la página alojada.Para clientes individuales:
{
  "type": "individual",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "address": {
    "line1": "233 South Wacker Drive",
    "line2": "Suite 4700",
    "city": "Chicago",
    "postalCode": "60606",
    "state": "IL",
    "country": "USA"
  }
}
Para clientes empresariales:
{
  "type": "business",
  "email": "contact@acmecorp.example.com",
  "phone": "+14155551234",
  "addresses": [
    {
      "type": "registered",
      "country": "USA",
      "line1": "123 Main Street",
      "city": "Chicago",
      "state": "IL",
      "postalCode": "60601"
    },
    {
      "type": "operating",
      "country": "USA",
      "line1": "456 Market Street",
      "city": "Chicago",
      "state": "IL",
      "postalCode": "60602"
    }
  ]
}
Guarda el id de la respuesta — lo necesitarás en los próximos pasos.
2

Generar un enlace de Términos de Servicio

Genera un enlace TOS y redirige al cliente para aceptar los Términos y Condiciones. Este paso puede realizarse en paralelo con la generación del enlace KYC/KYB.
POST https://api.spherepay.co/v2/customer/{id}/tos-link
Redirige al cliente a la URL devuelta para completar la aceptación de TOS.
3

Generar el enlace KYC o KYB alojado

En paralelo con el paso de TOS, genera el enlace de verificación alojado para tu cliente.
POST https://api.spherepay.co/v2/customer/{id}/kyc-link
Este único endpoint funciona tanto para clientes individuales (KYC) como empresariales (KYB) — SpherePay determina el flujo correcto según el type del cliente.Una vez que se genera el enlace, redirige al cliente a la URL devuelta. La experiencia alojada maneja:
  • Carga de documentos (documento de identidad, comprobante de domicilio)
  • Verificación de vivacidad facial
  • Verificación de contacto OTP
  • Carga de documentos empresariales y registro de UBO (para clientes empresariales)
Durante el flujo KYC/KYB, el cliente puede registrar una cuenta bancaria. Permanecerá en estado pending hasta que su identidad esté completamente verificada y el perfil de verificación alcance approved.
4

Redirigir o enviar el enlace a tu cliente

Redirige al cliente directamente desde tu aplicación, o envíale el enlace por correo electrónico o SMS. El cliente no necesita una cuenta existente de SpherePay para completar la verificación alojada.
5

Consultar el estado de verificación

Después de que el cliente complete el flujo alojado, consulta GET /v2/customer/{id} hasta que status en verificationProfiles alcance approved.
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"
}
Cuando required esté vacío y status sea approved, el cliente está completamente incorporado y listo para transferir.
Consulta en un intervalo razonable — por ejemplo, cada 30 segundos — en lugar de hacerlo continuamente. También puedes usar webhooks si tu integración los soporta.

​
Qué sigue

Una vez que el perfil de verificación del cliente sea approved, registra sus métodos de pago e inicia una transferencia.

Cuentas bancarias

Registra una cuenta bancaria para que el cliente pueda enviar o recibir fondos vía riel bancario.

Billeteras

Registra una dirección de billetera cripto para habilitar transferencias on-ramp y off-ramp.

API de Transferencias

Crea y gestiona transferencias una vez que el cliente haya registrado sus métodos de pago.

Perfil de verificación

Entiende los estados de verificación, arreglos de criterios y qué desencadena los cambios de estado.
Última modificación el 18 de junio de 2026