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.

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 negocio, y los usuarios deben cumplir los requisitos de KYC. En términos generales, esto significa proporcionar toda la información necesaria por adelantado o de a poco. De cualquier manera, configura tu integración para atender y responder a las solicitudes de Stripe.

1. Establece una URL de webhook de conexión en tu configuración de webhooks para observar la actividad, especialmente los eventos de tipo account.updated. Cuando uses la API Persons, también debes observar los eventos person.updated.
2. Inmediatamente después de crear una cuenta, revisa el atributo requirements.currently_due del objeto Account para ver si hay requisitos adicionales. Obtén la información requerida del usuario y actualiza la cuenta conectada.
3. Sigue observando las notificaciones de eventos account.updated para ver si cambia el hash requirements y si debes solicitarle al usuario información adicional cuando sea necesario.

Cuando proporcionas información adicional, no es necesario volver a enviar los datos ya verificados. Por ejemplo, si ya se verificó dob, no es necesario volver a proporcionar este dato en las siguientes actualizaciones.

Cambiar información después de la verificación

Una vez que se verifican un particular o una empresa, puedes modificar parte de su información, pero con algunas limitaciones. Consulta la API Update Account para conocer las limitaciones en función de la configuración de la cuenta conectada. Comunícate con soporte para realizar cambios fuera de estas limitaciones.

Determina si es necesaria la verificación

Cuando recibes un evento account.updated en webhooks o recuperas una cuenta con la API, recibes un objeto Account. Los atributos charges_enabled y payouts_enabled del objeto Account indican si la cuenta puede crear cargos y aceptar transferencias.

El objeto Account tiene un hash requirements que representa los requisitos necesarios para verificar la cuenta.

El hash requirements tiene las siguientes matrices:

• eventually_due: requisitos que podrías tener que recopilar si se alcanzan o no los umbrales correspondientes. Una vez que un requisito pasa a ser obligatorio, también aparece en la lista currently_due. Si un requisito pasa a ser obligatorio y su fecha de vencimiento es anterior al current_deadline existente, current_deadline cambia a la fecha de entrada en vigor del umbral correspondiente.
• currently_due: Requirements that you must collect by the current_deadline for the account to remain active. The currently_due requirement is a subset of eventually_due.
• past_due: Requirements that have disabled capabilities because they weren’t verified before the current_deadline. The past_due requirement is a subset of currently_due.
• errors: Detalles sobre errores de validación y verificación que requieren que se vuelvan a recopilar requisitos particulares en currently_due o past_due.
  • requirement: identifica el requisito correspondiente al error.
  • code: un valor de enumeración que describe por qué el requisito no es válido o no se puede verificar.
  • reason: un mensaje en inglés que describe el error con más detalle. La cadena de motivo también puede sugerir cómo resolver el error.
• disabled_reason: Describes why the account isn’t enabled and why it can’t process charges or transfers.
• current_deadline: Date that the requirements in currently_due must be collected by to keep the account active. It represents the earliest deadline across all of the account’s requested capabilities and risk requirements, including any hidden capabilities.
• pending_verification: requisitos que podrían llegar a exigirse en función de los resultados de la verificación o revisión. Es una matriz vacía a menos que haya una verificación asincrónica pendiente. La verificación incorrecta pasa un requisito a eventually_due, currently_due o past_due. Un requisito sujeto a verificaciones fallidas y pendientes también puede permanecer en pending_verification.

En el siguiente ejemplo se 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 errors de verificación.

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "disabled_reason": null,
      "current_deadline": 1529085600,
      "past_due": [],
      "currently_due": [
          "company.tax_id",
          "company.verification.document",
          "tos_acceptance.date",
          "tos_acceptance.ip"
      ],
      "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"
      ],
      "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"
          },
      ]
  },
  ...
}

Si requirements.currently_due contiene entradas, marca requirements.current_deadline. El current_deadline es una marca de tiempo de Unix que identifica cuándo se necesita información. Por lo general, si Stripe no recibe la información antes del current_deadline, se deshabilitan las transferencias en la cuenta. Sin embargo, pueden aplicarse otras consecuencias en algunas situaciones. 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 los cargos.

Por otro lado, la propiedad requirements.disabled_reason puede tener un valor. El valor es una cadena que describe el motivo por el cual esta cuenta no puede hacer transferencias o cargos. En algunos casos, 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 una cuenta en la página Cuentas conectadas para determinar el disabled_reason de una cuenta. Es posible que puedas proporcionar información adicional en nombre de tus cuentas conectadas. Si el motivo de deshabilitación está asociado a una apelación, puede generar un enlace a un formulario para que la cuenta resuelva la apelación.

Errores de validación y verificación

The Account object includes a requirements.errors array that explains why the validation or verification requirements haven’t been met, which you need to enable your account and capabilities. The errors array has the following attributes:

• requirement: especifica qué información se necesita de la matriz currently_due.
• code: Indica el tipo de error ocurrido. Consulta la referencia de API para conocer todos los códigos de error posibles.
• reason: explica por qué se produjo el error y cómo resolverlo.

El siguiente ejemplo muestra cómo se vería la matriz errors si una cuenta tuviera requisitos currently_due. En el ejemplo, se muestra el motivo por el cual la información enviada no se puede usar para habilitar la cuenta y cómo resolver el error. Si la verificación o validación falla, los requisitos pueden reaparecer en currently_due con información de error. Establece un webhook de Connect para recibir el evento account.updated y recibir estas actualizaciones.

{
  "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, pero no hay requisitos que venzan en este momento, se activa un webhook que indica que la información solicitada vence más adelante.

Información de la empresa

When information about a business is submitted, Stripe verifies the new information. For example, Stripe might verify that the provided business URL is valid, reachable, and includes information about the business. To check the status of verification information regarding a business, retrieve the Account object’s requirements hash.

Esta es la lista de errores relacionados con la verificación de la información de la empresa:

Descripciones de los cargos en el extracto bancario

Stripe valida la descripción del cargo en el extracto bancario y el prefijo de dicha descripción cuando se configuran en una cuenta. Por ejemplo, Stripe podría verificar que la descripción del cargo en el extracto bancario proporcionada coincida con la descripción de la empresa. Al validar que la descripción del cargo en el extracto bancario coincide con la descripción de la empresa, Stripe utiliza los primeros 22 caracteres de la descripción, que representan la parte que se proporciona a las redes de tarjeta. La descripción de una empresa coincide estrechamente con el business_profile.name, business_profile.url o nombre de la empresa o el particular de la cuenta.

To retrieve the status of verification information regarding statement descriptors, review the requirements on the Account object. Below is a list of errors related to statement descriptor verification:

Representantes de la empresa

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

• Companies only: Use the Persons API to add the information to a Person object associated with the Account object.
• Solo particulares: Puedes usar la API Persons o el hash individual en el objeto Account.
• A combination of individuals and companies: Use the Persons API to add the information to a Person object associated with the account. That lets you use the same process for all of your connected accounts, regardless of their type.

Para recuperar el estado de la información de verificación de una persona, usa el hash requirements.

Esta es la lista de errores relacionados con la verificación de personas:

Documentos aceptados para la verificación por país

Para obtener información sobre los requisitos de documentos específicos, consulta Documentos de verificación aceptables por país.

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.

To retrieve the status of verification information regarding an account’s company, use the Account object’s company.verification subhash:

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

You can look up the definition for each verification attribute on the Account object.

Gestiona los problemas de verificación de documentos

Los problemas con los documentos de identidad, ya sea con los archivos cargados o con su uso para validar otra información, causan muchos errores de verificación de requisitos. Para ayudarte a reconocer y gestionar los problemas más comunes, en las tablas que aparecen a continuación se enumeran los valores de error de requisitos de code relacionados con problemas con la documentación y proporcionan orientación para resolverlos.

Los siguientes errores se relacionan con los archivos de documentos cargados:

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

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

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

Gestiona los errores de verificación de la URL

Las URL para empresas de ecommerce deben cumplir con ciertos estándares de redes de tarjetas. Para cumplir con estos estándares, Stripe lleva a cabo una serie de verificaciones al revisar las URL. Para obtener información sobre las prácticas recomendadas para las URL y los elementos comunes para empresas de ecommerce, consulta la lista de verificación del sitio web.

In many cases, you can resolve business URL verification errors by generating a remediation link from your platform Dashboard. Otherwise, update the Account object’s business_profile.url. If you resolve the error another way, such as by fixing a problem with the company’s website, trigger re-verification by changing the URL on the Account object to any other value, then immediately changing it back.

No todos los problemas relacionados con las URL se pueden resolver con la API. Ciertos tipos de errores de verificación de URL requieren información adicional sobre cómo acceder al sitio web de la cuenta conectada o para certificar que la cuenta está exenta de los requisitos de URL. Este tipo de problemas requieren que tú o tu cuenta conectada proporcionen información complementaria.

Si no puedes resolver el problema, dirige tu cuenta conectada a comunícate con el soporte de Stripe.

Para ayudarte a reconocer y gestionar los problemas más comunes, en la siguiente tabla se enumeran los valores de error de requisito code relacionados con problemas con la URL de la empresa y proporciona orientación para resolverlos.

Administra los requisitos de detección de vida

An account can have one or more Person objects with a proof_of_liveness requirement. A proof_of_liveness requirement might require collection of an electronic ID credential such as MyInfo in Singapore, or by using Stripe Identity to collect a document or selfie. We recommend using Stripe-hosted or embedded onboarding to satisfy all variations of the proof_of_liveness requirement.

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -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

Gestionar la verificación de identidad

In some cases, depending on how much of an account’s identity information Stripe has been able to verify, we might ask you to upload one or more documents. Required documents appear in the Account object’s requirements hash.

Las siguientes entradas en requirements.currently_due identifican los documentos que debes cargar:

• 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 donde conste la dirección del usuario, como una factura de servicios públicos.
• company.verification.document: se solicita un comprobante de un documento de la entidad donde conste el número de ID de entidad de la empresa, como el acta constitutiva de la empresa.

El proceso para cargar un documento consta de dos pasos:

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

Cargar un archivo

Para cargar un archivo, utiliza la API Create File mediante una PUBLICACIÓN para enviar los datos del archivo como parte de una solicitud multipart/form-data.

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

Pass the file data in the file parameter and set the purpose parameter according to the Account or Person object that will hold the document. To identify the purpose, look up the property in the API Reference.

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

Esta 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

After you upload the file and receive a representative token, update the Account or Person object and provide the file ID in the appropriate parameter.

Veamos un ejemplo de un documento de identidad:

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

Veamos un ejemplo de un documento de la empresa:

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

Esta actualización cambia verification.status a pending. 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 requisitos asociada contiene un error con un code y description que describen la causa. El valor description contiene un mensaje legible por humanos, como «La imagen suministrada no es legible», que es seguro para presentarlo al usuario de tu cuenta, pero no está localizado. El valor code es una cadena como verification_document_not_readable, que puedes usar para localizar mensajes de error 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 alojada con Stripe Identity

Puedes usar Stripe Identity para cumplir con el requisito de person.verification.document a fin de recopilar un documento y adjuntarlo directamente a la cuenta.

Create a VerificationSession. Specify the related_person parameter to associate the collected verification data with the Person object requiring the document, as shown in the following example.

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

Después de crear la VerificationSession, usa el client_secret devuelto para mostrarle el cuadro de diálogo de identidad al usuario o redirigir al usuario a la url. La cuenta se actualiza automáticamente al completar la verificación.

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.

Gestiona las verificaciones de riesgos

Stripe informa los requisitos de riesgo y cumplimiento de la normativa en el atributo accounts.requirements. Estos requisitos siguen el esquema: <id>.<requirement_description>.<resolution_path>:

• id identifica de manera única la información que necesita Stripe o nuestros socios financieros. Este identificador siempre lleva el prefijo interv_ para indicar que se trata de 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:
  • challenge: las cuentas conectadas deben responder directamente a las indicaciones de desafío. 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.
  • form: las cuentas conectadas pueden completar solicitudes de formularios, o puedes completarlas en su nombre.
  • support: el requisito no se puede procesar directamente. Comunícate 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: puedes integrar componentes de Connect directamente en tu sitio web. Cuando surja un requisito, dirige a los usuarios al componente integrado onboarding de cuentas, donde se les solicitará que completen los requisitos pendientes directamente en tu interfaz de usuario. También puedes usar el componente integrado Aviso de notificación para solicitar a tus usuarios que indiquen los requisitos pendientes.
• Onboarding alojado de Stripe: puedes generar enlaces para dirigir a tus cuentas conectadas a la finalización de los requisitos pendientes mediante programación a través de enlaces de cuentas o de forma manual en el Dashboard de tu plataforma.
• Completa los requisitos en nombre de tus cuentas: puedes usar el Dashboard de tu plataforma para identificar y completar los requisitos de riesgo basados en formularios a partir de los datos de la cuenta conectada en nombre de tus cuentas.

En la tabla siguiente se proporcionan más detalles sobre las posibles descripciones de los requisitos relacionados con el riesgo y el cumplimiento de la normativa.