Gerenciar verificação com a API

As plataformas Connect que fazem onboarding de contas conectadas usando a API devem fornecer à Stripe as informações necessárias para fins de Conheça seu Cliente (KYC) e para habilitar funções de conta. Elas próprias devem coletar os dados e usar as APIs Accounts e Persons para fornecê-los à Stripe. Em seguida, verificamos as informações, solicitando mais detalhes quando necessário.

Processo de verificação

Antes de habilitar cobranças e repasses em uma conta conectada, a Stripe precisa de alguns dados que variam em função de:

• O país de origem das contas conectadas
• O tipo de contrato de serviços aplicável às contas conectadas
• As funções solicitadas para as contas conectadas
• O business_type (por exemplo, individual ou empresa) e a company.structure (por exemplo, public_corporation ou private_partnership)

As plataformas precisam escolher o fluxo de onboarding adequado para que as empresas e usuários cumpram os requisitos de KYC. De maneira geral, isso significa informar de forma antecipada ou incremental todos os dados necessários. De qualquer forma, configure sua integração para observar e responder às solicitações da Stripe.

1. Estabeleça um URL do webhook do Connect nas configurações do webhook para observar atividades, especialmente eventos do tipo account.updated. Ao usar a API Persons, você também deve observar os eventos person.updated.
2. Imediatamente após a criação de uma conta, verifique se há requisitos adicionais no atributo requirements.currently_due do objeto Account. Obtenha os dados necessários do usuário e atualize a conta conectada.
3. Continue observando as notificações de evento account.updated para ver se o hash requirements muda e, se necessário, entre em contato com o usuário para obter informações adicionais.

Quando você informa dados adicionais, não precisa enviar novamente dados já verificados. Por exemplo, se dob já foi verificada, você não precisa informá-la novamente nas atualizações seguintes.

Alterar dados após a verificação

Depois que uma pessoa física ou jurídica é verificada, você pode alterar alguns dados, com limitações. Consulte a API Update Account para ver as limitações baseadas na configuração da conta conectada. Fale com o suporte para fazer alterações fora dessas limitações.

Determinar se a verificação é necessária

Quando você recebe um evento account.updated no seu webhook ou busca uma conta com a API, recebe um objeto Account. Os atributos charges_enabled e payouts_enabled do objeto Account indicam se a conta pode criar cobranças e aceitar repasses.

O objeto Account tem um hash requirements que representa os requisitos necessários para verificar a conta.

O hash requirements tem as seguintes matrizes:

• eventually_due: requisitos que podem ser coletados dependendo de os limites correspondentes serem atingidos. Depois que um requisito se torna obrigatório, ele também aparece na lista currently_due. Se um requisito se tornar obrigatório e a data de vencimento for anterior ao current_deadline existente, o current_deadline muda para a data de entrada em vigor do limite correspondente.
• currently_due: requisitos que devem ser coletados até current_deadline para que a conta permaneça active. currently_due é um subconjunto de eventually_due.
• past_due: requisitos que desativaram funções porque elas não foram verificadas antes de current_deadline. past_due é um subconjunto de currently_due.
• errors: detalhes sobre falhas de validação e verificação que exigem que requisitos específicos em currently_due ou past_due sejam coletados novamente.
  • requirement: identifica o requisito correspondente ao erro.
  • code: um valor de enumeração que descreve por que o requisito é inválido ou não pode ser verificado.
  • reason: uma mensagem em inglês descrevendo o erro com mais detalhes. A string de motivo também pode sugerir como resolver o erro.
• disabled_reason: descreve por que a conta não está ativada e por que ela não pode processar cobranças ou transferências.
• current_deadline: data até a qual os requisitos em currently_due devem ser coletados para manter a conta active. Ela representa o prazo mais rápido entre todos os requisitos de recursos e riscos solicitados pela conta, incluindo quaisquer recursos ocultos.
• pending_verification: requisitos que podem se tornar obrigatórios, dependendo dos resultados da verificação ou revisão. É uma matriz vazia, a menos que uma verificação assíncrona esteja pendente. Uma verificação malsucedida muda um requisito para eventually_due, currently_due ou past_due. Um requisito sujeito a verificações malsucedidas e pendentes também pode permanecer em pending_verification.

O exemplo abaixo mostra a aparência do hash requirements para dados de uma conta que estão com os status currently_due, eventually_due e que causam errors de verificação.

{
  "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"
          },
      ]
  },
  ...
}

Se requirements.currently_due contiver entradas, marque requirements.current_deadline. O current_deadline é um carimbo de data e hora Unix que identifica quando os dados são necessários. Normalmente, se a Stripe não receber os dados até current_deadline, os repasses na conta serão desativados. No entanto, outras consequências podem se aplicar em algumas situações. Por exemplo, se os repasses já estiverem desativados e a conta não responder às nossas consultas, Stripe poderá desativar também o processamento de cobranças.

Separadamente, a propriedade requirements.disabled_reason pode ter um valor. O valor é uma string que descreve por que esta conta não pode realizar repasses ou cobranças. Em alguns casos, plataformas e contas conectadas podem enviar um formulário para resolver ou recorrer do motivo.

• Contas conectadas com acesso ao Stripe Dashboard completo, incluindo contas Standard, podem acessar dados adicionais (se disponíveis) no Dashboard.
• As plataformas podem procurar uma conta na página Contas conectadas para determinar o disabled_reason da conta. Talvez você possa fornecer dados adicionais em nome de suas contas conectadas. Se o motivo da desativação estiver associado a um recurso, você poderá gerar um link para um formulário para a conta a fim de resolver o recurso.

Erros de validação e verificação

O objeto Account inclui uma matriz requirements.errors que explica os motivos de falha no cumprimento de requisitos de validação ou verificação necessários para ativar contas e funções. A matriz errors tem estes atributos:

• requirement: especifica os dados da matriz currently_due que são necessários.
• code: indica o tipo de erro ocorrido. Consulte a referência da API para ver todos os possíveis códigos de erro.
• reason: explica o motivo do erro e como resolvê-lo.

O exemplo abaixo mostra a aparência da matriz errors para uma conta que tem requisitos com o status currently_due. O exemplo mostra o motivo da impossibilidade de usar os dados enviados para ativar a conta e como resolver o erro. Se a verificação ou a validação falhar, os requisitos poderão aparecer novamente em currently_due com informações sobre o erro. Defina um webhook do Connect para receber o evento account.updated e obter essas atualizações.

{
  "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.",
          }
      ]
  },
  ...
}

Se uma verificação ou validação falha, mas não há requisitos não informados no momento, um webhook é acionado para indicar que dados obrigatórios são necessários.

Dados comerciais

Quando os dados de uma empresa são enviados, a Stripe verifica os novos dados. Por exemplo, a Stripe pode verificar se o URL da empresa informado é válido, acessível e inclui informações sobre a empresa. Para verificar o status dos dados de verificação de uma empresa, acesse o hash requirements da Account.

Esta é a lista de erros de verificação de dados comerciais:

Descrições no extrato

A Stripe valida a descrição no extrato e o prefixo dessa descrição no extrato quando definidos em uma conta. Por exemplo, a Stripe pode verificar se a descrição no extrato fornecida corresponde à descrição da empresa. Quando valida se a descrição no extrato corresponde à descrição da empresa, a Stripe usa os 22 primeiros caracteres da descrição no extrato, que representa a parte fornecida às bandeiras de cartão. Uma descrição de empresa é uma correspondência próxima do business_profile.name, business_profile.url da conta ou do nome da empresa ou indivíduo.

Para recuperar o status dos dados de verificação das descrições no extrato, revise requirements no objeto Account. Esta é a lista de erros de verificação de descrição no extrato:

Representantes da empresa

Você precisa coletar e enviar dados sobre as pessoas associadas a uma conta conectada. O processo depende de suas contas conectadas serem pessoas físicas ou jurídicas:

• Somente empresas: Use a API Persons para adicionar os dados a uma Person associada à Account.
• Apenas pessoas físicas: Você pode usar a API Persons ou o hash individual no objeto Account.
• Uma combinação de pessoas físicas e jurídicas: Use a API Persons para adicionar os dados a uma Person associada à conta. Isso permite usar o mesmo processo para todas as contas conectadas, independentemente do tipo.

Para recuperar o status dos dados de verificação de uma pessoa, use o hash requirements.

Esta é a lista de erros de verificação de pessoa:

Documentos de verificação aceitos por país

Para saber mais sobre requisitos específicos de documentos, consulte Documentos de verificação aceitos por país.

Informações da empresa

Durante o processo de verificação, pode ser necessário coletar informações sobre a empresa de uma conta.

Para recuperar o status dos dados de verificação relacionados à empresa de uma conta, use o subhash company.verification de Account:

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

Você pode procurar a definição de cada atributo de verificação no objeto Account.

Gerenciar problemas de verificação de documentos

Problemas com documentos de identificação, seja com arquivos carregados ou com o uso deles para validar outros dados, causam muitos erros de verificação de requisitos. Para ajudar a reconhecer e gerenciar os problemas mais comuns, as tabelas a seguir listam os valores de code de erros de requisitos relacionados a problemas de documentos e fornecem orientações para resolvê-los.

Os seguintes erros estão relacionados a arquivos de documentos carregados:

Os seguintes erros estão relacionados à verificação de identidade:

Os seguintes erros estão relacionados à verificação de empresa:

Os seguintes erros estão relacionados à verificação de relacionamento:

Gerenciar erros de verificação de URL

Os URLs de empresas de e-commerce precisam estar em conformidade com determinados padrões das redes de cartão. Para cumprir esses padrões, a Stripe realiza uma série de verificações durante a revisão de URLs. Para saber mais sobre as práticas recomendadas para URLs e elementos comuns para empresas de e-commerce, consulte a lista de verificação de sites.

Em muitos casos, você pode resolver erros de verificação de URL da empresa gerando um link de remediação no Dashboard da sua plataforma. Caso contrário, atualize o business_profile.url da Account. Se você resolver o erro de outra maneira, como corrigindo um problema com o site empresarial, acione a nova verificação alterando o URL em Account para qualquer outro valor e, em seguida, alterando-o imediatamente de volta para o valor correto.

Nem todos os problemas relacionados ao URL podem ser resolvidos usando a API. Alguns tipos de erros de verificação de URL exigem informações adicionais sobre como acessar o site da conta conectada ou para atestar que a conta está isenta de requisitos de URL. Esses tipos de problema exigem que você ou a conta conectada forneça dados complementares.

Se não conseguir resolver o problema, oriente a conta conectada a falar com o suporte da Stripe.

Para ajudar a reconhecer e gerenciar os problemas mais comuns, a tabela a seguir lista os valores de code de erros de requisitos relacionados a problemas com o URL da empresa e fornece orientações para resolvê-los.

Gerenciar requisitos de presença viva

Uma conta pode ter uma ou mais pessoas com um requisito de proof_of_liveness. Um requisito de proof_of_liveness pode exigir a coleta de uma credencial de identificação eletrônica, como MyInfo em Singapura ou usando o Stripe Identity para coletar um documento ou selfie. Recomendamos usar o onboarding hospedado ou integrado da Stripe para cumprir todas as variações do 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

Gerenciar verificação de identidade

Em alguns casos, dependendo da quantidade de dados de identificação de uma conta verificada pela Stripe, podemos solicitar que você carregue um ou mais documentos. Os documentos necessários aparecem no hash requirements de Account.

As seguintes entradas em requirements.currently_due identificam os documentos que você deve carregar:

• person.verification.document: exige uma digitalização ou foto colorida de uma forma de identificação aceitável.
• person.verification.additional_document: exige uma digitalização ou foto colorida de um documento que verifique o endereço do usuário, como uma conta de serviços públicos.
• company.verification.document: exige uma comprovação de documento de entidade que estabeleça o número de identificação da entidade da empresa, como o seu estatuto social.

Carregar um documento é um processo em duas etapas:

1. Carregue o arquivo para a Stripe
2. Anexe o arquivo à conta

Carregar um arquivo

Para carregar um arquivo, use a API Create File usando um POST para enviar os dados do arquivo como parte de uma solicitação multipart/form-data.

O arquivo carregado deve cumprir estes requisitos:

• Imagem colorida (8.000 pixels por 8.000 pixels ou menor)
• 10 MB ou menos
• Os documentos de identidade estão no formato JPG ou PNG
• Os documentos de endereço ou pessoa jurídica estão no formato JPG, PNG ou PDF

Passe os dados do arquivo no parâmetro file e defina o parâmetro purpose de acordo com a propriedade Account ou Person que manterá o documento. Para identificar a finalidade, procure a propriedade na referência da 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"

Essa solicitação carrega o arquivo e retorna um token:

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

Use o valor id do token para vincular o arquivo a uma conta conectada para verificação de identidade.

Anexar o arquivo

Depois de carregar o arquivo e receber um token de representante, atualize Account ou Person e forneça o ID do arquivo no parâmetro apropriado.

Este é um exemplo de um documento de identificação:

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

Este é um exemplo de um documento de empresa:

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

Essa atualização altera verification.status para pending. Se for necessário verificar mais pessoas, use a API Persons para atualizá-las.

Confirmar verificação de identidade

O cumprimento de todos os requisitos de verificação de identidade de uma pessoa ou empresa aciona uma notificação de webhook v2.core.account_person.updated ou v2.core.account[identity].updated, sinalizando que o processo de verificação está concluído.

A Stripe pode levar de alguns minutos a alguns dias úteis para verificar uma imagem, dependendo de sua legibilidade.

Se a tentativa de verificação falhar, a entrada de requisito associada conterá um erro com um code e description descrevendo a causa. A description contém uma mensagem legível para humanos, como “A imagem fornecida não está legível”, que pode ser apresentada com segurança ao usuário da conta, mas não está localizada. O valor code é uma string como verification_document_not_readable, que você pode usar para localizar mensagens de erro para os usuários da conta.

A falha na verificação também aciona uma notificação de webhook v2.core.account_person.updated ou v2.core.account[identity].updated.

Gerenciar verificações de risco

A Stripe relata requisitos de risco e conformidade no atributo accounts.requirements. Esses requisitos seguem o esquema: <id>.<requirement_description>.<resolution_path>:

• O id identifica exclusivamente os dados necessários para a Stripe ou para os nossos parceiros financeiros. Esse identificador é sempre prefixado com interv_ para indicar que é um requisito de verificação de risco.
• requirement_description descreve especificamente os dados necessários para concluir o requisito, como identity_verification, rejection_appeal e assim por diante.
• resolution_path especifica como você ou sua conta conectada pode fornecer os dados solicitados:
  • challenge: as contas conectadas precisam responder diretamente às solicitações de desafio. Muitas vezes, eles exigem dados confidenciais, como uma conta bancária, ou informações que só o titular da conta pode fornecer, como uma selfie.
  • form: as contas conectadas podem preencher solicitações de formulário ou você pode preenchê-las em nome delas.
  • support: o requisito não pode ser acionado diretamente. Fale com o suporte da Stripe.

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

Depois de satisfazer um caminho de resolução, o valor do caminho de resolução do requisito pode mudar para support e o requisito também aparece na seção pending_verification do hash de requisitos. A Stripe verifica os dados enviados e descarta o requisito como resolvido ou publica um novo requisito vencido.

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

É possível remediar requisitos de risco e conformidade de qualquer uma das seguintes maneiras, dependendo do tipo de requisito:

• Componentes integrados do Connect: você pode incorporar componentes do Connect diretamente no seu site. Quando surgir um requisito, direcione os usuários para o componente integrado de onboarding de conta, onde eles serão solicitados a concluir requisitos pendentes diretamente na sua IU. Você também pode usar o componente integrado de banner de notificação para solicitar aos usuários o cumprimento de eventuais requisitos pendentes.
• Onboarding hospedado pela Stripe: você pode gerar links para direcionar suas contas conectadas a concluir automaticamente requisitos pendentes por meio de links de conta ou manualmente no Dashboard da plataforma.
• Resolva pendências em nome de suas contas: você pode usar o Dashboard da sua plataforma para identificar e cumprir requisitos de risco baseados em formulário com base nos dados da conta conectada em nome de suas contas.

A tabela a seguir oferece mais detalhes sobre possíveis descrições de requisitos relacionados a risco e conformidade.