Gestionar la verificación con la API

Las plataformas Connect que integran cuentas conectadas a través de la API deben facilitar a Stripe la información requerida a los fines de Conozca a su cliente (KYC) y para habilitar las funcionalidades de cuenta. Deben recopilar la información y utilizar las API Accounts y Persons para proporcionársela a Stripe. Luego, verificamos la información y solicitamos más detalles cuando sea necesario.

Las plataformas responsables también deben monitorear los estados de los requisitos de sus cuentas conectadas y gestionar cualquier actualización de manera oportuna.

Proceso de verificación

Antes de habilitar cargos y transferencias a cuentas bancarias para una cuenta conectada, Stripe necesita determinada información que varía según:

• El país de origen de las cuentas conectadas
• El tipo de contrato de servicio que se aplica a las cuentas conectadas
• Las funcionalidades solicitadas para las cuentas conectadas
• El business_type (por ejemplo, unipersonal o empresa) y company.structure (por ejemplo, public_corporation o private_partnership)

Las plataformas deben elegir el flujo de onboarding adecuado para su empresa y las cuentas conectadas deben cumplir los requisitos de KYC. Esto implica proporcionar toda la información necesaria en un solo paso o de a poco. De cualquiera de las dos maneras, configura tu integración para prestar atención a las solicitudes de Stripe.

1. Establece una URL de webhook Connect en tu configuración de webhook para estar atento a la actividad, especialmente a los eventos account.updated. Cuando uses la API Persons, también debes estar atento a los eventos person.updated.
2. Inmediatamente después de crear una cuenta, comprueba si hay requisitos adicionales en el atributo requirements.currently_due del objeto Cuenta. Obtén la información necesaria de la cuenta conectada y actualiza la Cuenta. Mientras requirements.currently_due no esté vacío, la Cuenta tiene requisitos pendientes que podrían restringir sus funcionalidades.
3. Sigue observando las notificaciones de eventos account.updated para ver si cambia el hash requirements y solicita información adicional a la cuenta conectada según sea necesario.

Cuando proporcionas información adicional, no es necesario volver a enviar los datos ya verificados. Por ejemplo, si ya se ha verificado la fecha de nacimiento, no es necesario volver a proporcionar este dato, a menos que se produzca un cambio.

Requisitos para revisar riesgos Stripe

Las revisiones de riesgo de una cuenta conectada de Stripe pueden agregar requisitos adicionales, que no puedes proporcionar usando la API. Puedes tomar medidas en tu Dashboard o la cuenta conectada puede proporcionarlos a través de un componente integrado de Connect, onboarding alojado en Stripe o un enlace de rectificación.

Determina si es necesaria la verificación

Los atributos charges_enabled y payouts_enabled de un objeto Cuenta indican si puede crear cargos y aceptar transferencias.

Si alguno de esos atributos es falso, comprueba el hash de requisitos de la cuenta con el fin de determinar qué información se necesita para habilitar los cargos y las transferencias.

El hash requirements contiene las siguientes propiedades:

El siguiente ejemplo muestra cómo se vería el hash requirements si una cuenta tuviera alguna información currently_due, alguna información eventually_due y alguna información que planteara errores de verificación.

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "alternatives": [],
      "current_deadline": 1529085600,
      "currently_due": [
          "company.tax_id",
          "company.verification.document",
          "tos_acceptance.date",
          "tos_acceptance.ip"
      ],
      "disabled_reason": null,
      "errors": [
          {
            "requirement": "company.verification.document",
            "reason": "The company name on the account couldn't be verified. Either update your business name or upload a document containing the business name.",
            "code": "failed_name_match"
          },
      ]
      "eventually_due": [
          "company.address.city",
          "company.address.line1",
          "company.address.postal_code",
          "company.address.state",
          "company.tax_id",
          "company.verification.document",
          "external_account",
          "tos_acceptance.date",
          "tos_acceptance.ip"
      ],
      "past_due": [],
      "pending_verification": []
  },
  ...
}

Si requirements.currently_due contiene entradas, marca requirements.current_deadline, la cual es una marca de tiempo Unix. Stripe suele deshabilitar las transferencias a la cuenta si no recibimos la información antes del current_deadline. Sin embargo, en algunas situaciones pueden aplicarse otras consecuencias. Por ejemplo, si las transferencias ya están deshabilitadas y la cuenta no responde a nuestras consultas, Stripe también podría deshabilitar la capacidad de procesar pagos.

Por separado, la propiedad requirements.disabled_reason puede contener una cadena que describa por qué la cuenta tiene ciertas funcionalidades deshabilitadas. En algunas situaciones, las plataformas y las cuentas conectadas pueden enviar un formulario para resolver o apelar el motivo.

• Las cuentas conectadas con acceso al Dashboard de Stripe completo, incluidas las cuentas Standard, pueden acceder a información adicional (si está disponible) en el Dashboard.
• Las plataformas pueden buscar el disabled_reason de una cuenta en la página Cuentas conectadas. Es posible que puedas proporcionar información adicional en nombre de tus cuentas conectadas. Si el motivo deshabilitado está asociado a una apelación, puedes generar un enlace a un formulario para que la cuenta resuelva la apelación.

Errores de validación y verificación

El objeto Cuenta incluye una matriz requirements.errors que explica por qué no se cumplieron los requisitos de validación o verificación. Debes cumplir estos requisitos para habilitar las funcionalidades de la cuenta.

La matriz de errores tiene los siguientes atributos:

En el siguiente ejemplo, se muestra una matriz de errores para una cuenta con requisitos currently_due, el motivo por el que la información enviada no se puede usar a fin de habilitar la cuenta y cómo resolver el error.

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "current_deadline": 1234567800,
      "currently_due": [
          "company.address.line1",
          "{{PERSON_ID}}.verification.document",
      ],
      "errors": [
          {
            "requirement": "company.address.line1",
            "code": "invalid_street_address",
            "reason": "The provided street address cannot be found. Please verify the street name and number are correct in \"10 Downing Street\"",
          },
          {
            "requirement": "{{PERSON_ID}}.verification.document",
            "code": "verification_document_failed_greyscale",
            "reason": "Greyscale documents cannot be read. Please upload a color copy of the document.",
          }
      ]
  },
  ...
}

Si la verificación o validación falla, los requisitos pueden reaparecer en currently_due, alternative_fields_due o eventually_due con información de error. Para recibir notificación de estos requisitos, establece un webhook Connect a fin de escuchar el evento account.updated.

Información de la empresa

Stripe verifica toda la información presentada sobre una empresa. Por ejemplo, si la URL de la empresa es válida, si se puede acceder a ella e incluye información sobre la empresa. Para comprobar el estado de la verificación, puedes recuperar el hash requirements en el objeto Cuenta.

Los siguientes errores se relacionan con la verificación de información de la empresa:

Consulta Gestionar errores de verificación de URL para resolver los siguientes errores de URL:

• invalid_url_denylisted
• invalid_url_format
• invalid_url_web_presence_detected
• invalid_url_website_business_information_mismatch
• invalid_url_website_empty
• invalid_url_website_inaccessible
• invalid_url_website_inaccessible_geoblocked
• invalid_url_website_inaccessible_password_protected
• invalid_url_website_incomplete
• invalid_url_website_incomplete_cancellation_policy
• invalid_url_website_incomplete_customer_service_details
• invalid_url_website_incomplete_legal_restrictions
• invalid_url_website_incomplete_refund_policy
• invalid_url_website_incomplete_return_policy
• invalid_url_website_incomplete_terms_and_conditions
• invalid_url_website_incomplete_under_construction
• invalid_url_website_other

Representantes de la empresa

Debes cobrar y enviar información sobre las personas asociadas a una cuenta conectada. El proceso depende de si tus cuentas conectadas son empresas, particulares o ambos.

En el caso de las empresas, usa la API Persons para agregar la información a un objeto Person asociado al objeto Cuenta. Con el objetivo de agregar documentos al hash verification en el objeto Person, primero usa la API Files a fin de cargar los archivos de documentos en los servidores de Stripe.

Para particulares, puedes crear una Person o agregar la información al hash individual en el objeto Cuenta.

Si tus cuentas conectadas incluyen tanto empresas como particulares, crea objetos Person para poder procesarlos de la misma manera.

Para controlar el estado de verificación de una Cuenta, puedes recuperar el hash de requirements.

Los siguientes errores están relacionados con la verificación de identidad:

Documentos aceptados para la verificación

Los tipos de documentos de identidad que acepta Stripe para las cuentas conectadas varían según el país y son los mismos que para otras cuentas de Stripe.

Información de la empresa

Durante el proceso de verificación, es posible que tengas que recopilar información sobre la empresa para una cuenta.

Para comprobar el estado de verificación, puedes recuperar el subhash company.verification en el objeto Cuenta.

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  ...
  "company": {
    "verification": {
      "document": null
    },
    ...
  },
  ...
}

Puedes buscar la definición de cada atributo de verificación en el objeto Account.

Descripciones de los cargos en el extracto bancario

Stripe valida la descripción del cargo en el extracto bancario y el prefijo de la descripción del cargo en el extracto bancario cuando los estableces en una Cuenta. Por ejemplo, podemos verificar que los primeros 22 caracteres, que se proporcionan a las redes de tarjeta, coincidan con la descripción de la empresa. Verificamos si coinciden estrechamente con el business_profile.name, business_profile.url de la Cuenta o con el nombre de la empresa o particular.

Para comprobar el estado de verificación de la descripción del cargo en el extracto bancario, puedes recuperar el hash requirements en el objeto Cuenta.

Los siguientes errores se relacionan con la verificación de la descripción del cargo en el extracto bancario:

Cómo gestionar problemas durante la verificación de documentos

Consulta la siguiente tabla para resolver los errores comunes de verificación de requisitos relacionados con los archivos de documentos cargados.

Si la verificación falla, no vuelvas a enviar el mismo archivo. Las cargas duplicadas fallan automáticamente.

Gestiona errores de verificación de la URL

Stripe’s terms of service require all e-commerce businesses to populate the business_profile.url property on their Account with a working URL of their business website when requesting the card_payments capability. A connected account is considered an e-commerce business if it promotes or sells any products or services through an online website, social media profile, or mobile application. For more information, see the Business website for account activation FAQ.

If the connected account doesn’t operate a website to promote their business, sell products, or accept payments, they’re required to provide the business_profile.product_description instead. A product description must detail the type of products being sold, as well as the manner in which the business charges its customers (for example, in-person transactions).

Las URL para las empresas ecommerce deben ajustarse a determinadas normas de las redes de tarjetas. A fin de poder cumplirlas, Stripe realiza varias verificaciones al revisar las URL. Obtén información sobre las prácticas recomendadas para las URL y los elementos comunes de las empresas ecommerce.

En muchos casos, puedes resolver los errores de verificación de URL si haces cualquiera de las siguientes acciones:

• Generar un enlace de rectificación desde el Dashboard.
• Cuando se actualiza la empresa_profile.url en el objeto Cuenta.

Si resuelves el error de otra manera (por ejemplo, utilizando el sitio web de la empresa para solucionar un problema), debes volver a realizar la verificación cambiando la URL del objeto Cuenta a cualquier otro valor y, a continuación, volviéndola a cambiar de inmediato.

No puedes usar la API para resolver todos los problemas relacionados con la URL. Ciertos errores de verificación de URL requieren información, por ejemplo, cómo acceder al sitio web de la cuenta conectada o para certificar que la cuenta está exenta de los requisitos de URL. Estos problemas requieren que tú o tu cuenta conectada proporcionen información complementaria.

Si no puedes resolver el problema, solicita a tu cuenta conectada que se ponga en contacto con el soporte de Stripe.

Consulta la siguiente tabla para resolver los errores de verificación de URL.

Gestiona los requisitos de vida

Una cuenta puede tener uno o más objetos Person con el requisito proof_of_liveness. Un requisito proof_of_liveness puede requerir la obtención de una credencial de identificación electrónica como MyInfo en Singapur o usar Stripe Identity para recopilar un documento o selfie. Te recomendamos usar onboarding alojado o integrado en Stripe a fin de satisfacer todas las variaciones del requisito proof_of_liveness.

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
"{{CONNECTED_ACCOUNT_ID}}" \
  --data-urlencode refresh_url="https://example.com/refresh" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding \
  -d "collection_options[fields]"=currently_due

Gestiona la verificación de identidad

Según la información de identidad que hayamos verificado para una cuenta, es posible que te pidamos que cargues uno o más documentos. Estos aparecerán en el hash requirements del objeto Cuenta.

Debes cargar los documentos que aparecen en requirements.currently_due:

• person.verification.document: se solicita una copia escaneada o una foto en color de una forma de identificación aceptable.
• person.verification.additional_document: se solicita una copia escaneada o una foto en color de un documento que conste la dirección del usuario, como una factura de servicios públicos.
• company.verification.document: carga un comprobante de un documento de entidad que conste el número de ID de entidad de la empresa, como los estatutos de constitución de esta.

Cuando requirements.alternatives.alternative_fields_due incluye requisitos verification.document, estos pueden utilizarse como alternativa a requirements.alternatives.original_fields_due.

Por razones de seguridad, Stripe no acepta documentos de identidad por correo electrónico. La carga de un documento es un proceso de dos pasos:

1. Cargar el archivo en Stripe.
2. Adjuntar el archivo a la cuenta.

Cargar un archivo

Con el objetivo de cargar un archivo, llama a la API Files para crearlo.

El archivo cargado debe cumplir con los siguientes requisitos:

• Imagen en color (8,000 pixeles por 8,000 pixeles, como mínimo)
• 10 MB o menos
• Los documentos de identidad están en formato JPG o PNG
• Las constancias de dirección o documentación de la entidad jurídica están en formato JPG, PNG o PDF

Especifica los datos del archivo en el parámetro archivo y establece el parámetro propósito de acuerdo con el objeto Account o Person que retendrá el documento. Para identificar el propósito, busca la propiedad en la referencia de la API.

curl https://files.stripe.com/v1/files \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" \
  -F "purpose"="identity_document" \
  -F "file"="@/path/to/a/file"

La siguiente solicitud carga el archivo y devuelve un token:

{
  "id": 
"{{FILE_ID}}",
  "created": 1403047735,
  "size": 4908
}

Usa el valor id del token para adjuntar el archivo a una cuenta conectada para la verificación de identidad.

Adjuntar el archivo

Después de cargar el archivo y recibir un token representativo, actualiza el objeto Account o Person e ingresa la ID del archivo en el parámetro correspondiente.

El siguiente ejemplo es para un documento de identidad emitido por un organismo público:

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons/
{{PERSON_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "verification[document][front]"=
"{{FILE_ID}}"

El siguiente ejemplo es para un documento de la empresa:

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "company[verification][document][front]"=
"{{FILE_ID}}"

Esta actualización cambia el verification.status a pendiente. Si tienes que verificar a otra persona, utiliza la API Persons para actualizarla.

Confirma la verificación de la identidad

Si cumpliste con todos los requisitos de verificación de identidad de una persona o empresa, se envía una notificación de webhooks v2.core.account_person.updated o v2.core.account[identity].updated que indica que el proceso de verificación finalizó.

Stripe puede tardar desde unos minutos hasta unos días hábiles en verificar una imagen, según su legibilidad.

Si el intento de verificación falla, la entrada de requisito asociada contiene un error con un código y una descripción que explican la causa. La descripción es un mensaje en lenguaje sencillo no localizado, como «La imagen suministrada no es legible», que puedes presentar al usuario de tu cuenta. El valor del código es una cadena, como verification_document_not_readable, que puedes usar a fin de localizar mensajes de errores para los usuarios de tu cuenta.

El error de verificación también desencadena una notificación de webhooks v2.core.account_person.updated o v2.core.account[identity].updated.

Recopilación de documentos alojados con Stripe Identity

Puedes usar Stripe Identity para cumplir con un requisito de person.verification.document obteniendo un documento y adjuntándolo directamente a la cuenta. Sin embargo, no puedes usar Stripe Identity para cumplir con los requisitos de person.verification.additional_document o company.verification.document.

Crea una VerificationSession. Especifica el parámetro related_person para asociar los datos de verificación recopilados al objeto Person que requiere el documento, como se muestra en el siguiente ejemplo:

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d type=document \
  -d "related_person[account]"=
"{{CONNECTED_ACCOUNT_ID}}" \
  -d "related_person[person]"=
"{{PERSON_ID}}"

Después de crear la VerificationSession, usa el cliente_secret devuelto para mostrar el modal de identidad al usuario o redirigir al usuario a la url. La verificación completada actualiza automáticamente la cuenta.

Enviamos un evento account.updated a tu punto de conexión de webhooks cuando la cuenta completa la comprobación de identidad y actualiza su información.

Gestionar requisitos establecidos en formularios o soporte

Stripe informa los requisitos de riesgo y cumplimiento de la normativa en el hash requirements. Estos requisitos tienen el formato <id><requirement_description>.<resolution_path>.

• ID: identifica de manera única la información que Stripe o nuestros socios financieros necesitan. Este identificador siempre tiene el prefijo interv_ para indicar que es un requisito de verificación de riesgos.
• requirement_description: describe específicamente la información necesaria para completar el requisito, como identity_verification, rejection_appeal, etc.
• resolution_path: especifica cómo tú o tu cuenta conectada pueden proporcionar la información solicitada:
  • desafío: la cuenta conectada debe responder directamente a las indicaciones de desafío, que a menudo requieren información confidencial (como una cuenta bancaria) o información que solo el titular de la cuenta puede proporcionar (como una selfie).
  • formulario: la cuenta conectada puede completar las solicitudes de formulario o puedes completarlas en su nombre.
  • soporte: el requisito no es directamente procesable. Ponte en contacto con el soporte de Stripe.

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "current_deadline": 1234567800,
      "currently_due": [
          "{{REQUIREMENT_ID}}.restricted_or_prohibited_industry_diligence.form"
      ],
      "pending_verification": [],
      ...
  },
  ...
}

Después de cumplir con una ruta de resolución, el valor de la ruta de resolución del requisito puede cambiar a support y el requisito también aparece en la sección pending_verification del hash de requirements. Stripe verifica la información enviada y descarta el requisito como resuelto o publica un nuevo requisito actualmente pendiente.

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "current_deadline": 1234567800,
      "currently_due": [],
      "pending_verification": [
        "{{REQUIREMENT_ID}}.restricted_or_prohibited_industry_diligence.support"
      ],
      ...
  },
  ...
}

Puedes corregir los requisitos de riesgo y cumplimiento de la normativa de cualquiera de las siguientes maneras, en función del tipo de requisito:

• Componentes integrados de Connect: integra componentes Connect en tu sitio web y dirige a tus usuarios al componente integrado de onboarding de cuentas, en el cual se les solicitará que completen los requisitos de interfaz de usuario (IU) pendientes. Como alternativa, utiliza el componente integrado notification.banner a fin de solicitar a tus usuarios los requisitos pendientes.
• Onboarding alojado por Stripe: genera enlaces para dirigir a tus cuentas conectadas y completar los requisitos pendientes mediante programación con enlaces de cuenta o manualmente en el Dashboard de tu plataforma.
• Completa en nombre de tus cuentas: puedes usar el Dashboard de tu plataforma para identificar y completar requisitos de riesgo establecidos en formularios en nombre de tus cuentas desde la página de datos de la cuenta conectada.

La siguiente tabla proporciona más información sobre los requisitos relacionados con el riesgo y el cumplimiento de la normativa.