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.

Plataformas responsáveis também devem monitorar o status de necessidades de suas contas conectadas e lidar com quaisquer atualizações de forma oportuna.

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 melhor fluxo de onboarding para que suas empresas e usuários atendam aos requisitos KYC. Isso significa fornecer todas as informações necessárias desde o início ou de maneira gradual. De qualquer forma, configure sua integração para ficar atento e responder às solicitações da Stripe.

1. Estabeleça um URL de webhook Connect nas configurações de webhook para monitorar atividades, especialmente eventos conta.updated. Ao usar a API Persons, observe também eventos person.updated.
2. Imediatamente após criar uma conta, verifique o atributo da Account e quaisquer requisitos requirements.currently_due adicionais do objeto. Obtenha todas as informações necessárias da conta conectada e atualize a Account. Contanto que requirements.currently_due não esteja vazia, aAccount possui requisitos pendentes que podem restringir suas capacidades.
3. Continue dando atenção às notificações de evento de account.updated para ver se existem mudanças nos requirements de hash e solicite à conta conectada informações adicionais conforme o necessário.

Quando você fornece informações adicionais, você não precisa reenviar dados verificados anteriormente. Por exemplo, se o dob já estiver verificado, você não precisa fornecer novamente a menos que mude.

Requisitos de revisão de risco da Stripe

As análises de risco da Stripe em uma conta conectada podem adicionar requisitos extras, os quais você não pode fornecer usando a API. É possível tomar ação em seu dashboard, ou a conta conectada pode fornecê-los através de um componente Connect embutido,pelo onboarding proporcionado pela Stripe, ou por um link de remediação.

Determinar se a verificação é necessária

Os atributos charges_enabled e payouts_enabled em um objeto Account indicam se ele pode criar cobranças e aceitar repasses.

Se algum desses atributos for falso, verifique o hash de requisitos da conta para determinar quais informações são necessárias para habilitar cobranças e repasses.

O hash de requirements contém as seguintes propriedades:

O exemplo abaixo mostra como seria o hash requirements para dados de uma conta que está com os status currently_due, eventually_due e que causam erros de verificação.

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

Se requirements.currently_due contém entradas, marque requirements.current_deadline, que é um carimbo de data e hora Unix. Normalmente, a Stripe desativa repasses na conta se não recebermos as informações até a current_deadline. 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, a Stripe também pode desativar a capacidade de processar cobranças.

Separadamente, a propriedade requirements.disabled_reason pode conter uma string descrevendo o motivo da desativação de determinadas funções da conta. Em algumas situações, as plataformas e as 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 o disabled_reason de uma conta na página de contas conectadas. Você pode fornecer informações adicionais em nome de suas contas conectadas. Se o motivo da desativação estiver associado a um recurso, você pode gerar um Link para um formulário para que a conta resolva o recurso.

Erros de validação e verificação

O objeto Account inclui uma matriz requirements.errors que explica por que os requisitos de validação ou verificação não foram cumpridos. Você deve cumprir esses requisitos para pedir a ativação das funções da conta.

A matriz de erros tem os seguintes atributos:

O exemplo a seguir mostra uma matriz de erros para uma conta com requisitos que são currently_due, o motivo pelo qual as informações enviadas não podem ser usadas para ativar a conta e como resolver o erro.

{
  "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 a verificação ou validação não for bem-sucedida, os requisitos podem aparecer novamente em currently_due, alternative_fields_due ou eventually_due com informações de erro. Para receber a notificação desses requisitos, defina um Webhook Connect para ouvir o evento conta.updated.

Dados comerciais

A Stripe verifica todas as informações enviadas sobre uma empresa. Por exemplo, podemos verificar se o URL da empresa é válido, acessível e inclui informações sobre a empresa. Para verificar o status dessa verificação, você pode recuperar o hash de requirements no objeto Account.

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

Consulte Gerenciar erros de verificação de URL para resolver os seguintes erros:

• 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 da empresa

Você deve recolher e enviar informações sobre as pessoas associadas a uma conta conectada. O processo depende se suas contas conectadas são empresas, pessoas físicas ou ambas.

Para empresas, use a API Persons para adicionar as informações a um objeto Person associado ao objeto Account. Para adicionar documentos ao hash de verificação no objeto Person, primeiro use a API Files para carregar os arquivos de documento nos servidores da Stripe.

Para pessoas físicas, você pode criar uma Person ou adicionar as informações ao hash pessoa física no objeto Account.

Se suas contas conectadas incluem empresas e pessoas físicas, crie objetos Person para que você possa usar o mesmo processo para todas elas.

Para verificar o status de verificação de uma Account, você pode recuperar seu hash de requisitos.

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

Documentos de verificação aceitos

Os tipos de documentos de identificação que a Stripe aceita para contas conectadas variam conforme o país e são os mesmos que para outras contas Stripe.

Informações da empresa

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

Para verificar o status da verificação, você pode recuperar o subhash company.verification no objeto Conta.

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

É possível consultar a definição de cada atributo de verificação diretamente no objeto Account.

Descrições no extrato

A Stripe valida a descrição no extrato e o prefixo de descrição no extrato quando você os define em uma Account. Por exemplo, podemos verificar se os primeiros 22 caracteres, que são fornecidos às bandeiras de cartão, correspondem à descrição da empresa. Verificamos se eles correspondem ao business_profile.name, business_profile.url ou ao nome da empresa ou da pessoa física da Account.

Para verificar o status de verificação da descrição no extrato, você pode recuperar o hash requirements no objeto Account.

Os seguintes erros estão relacionados à verificação da descrição no extrato:

Gerenciar problemas de verificação de documentos

Consulte a tabela a seguir para resolver erros comuns de verificação de requisitos relacionados a arquivos de documento carregados.

Se a verificação falhar, não envie novamente o mesmo arquivo. Os uploads duplicados falham automaticamente.

Gerenciar erros de verificação de 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).

Os URLs para empresas de e-commerce devem estar em conformidade com determinados padrões de bandeiras de cartão. Para cumprir esses padrões, a Stripe realiza uma série de verificações ao revisar URLs. Saiba mais sobre as práticas recomendadas para URLs e elementos comuns para empresas de e-commerce.

Em muitos casos, você pode resolver erros de verificação de URL fazendo uma das seguintes ações:

• Gere um link de remediação no Dashboard da sua plataforma.
• Atualizando o empresa_profile.url no objeto Account.

Se você resolver o erro de outra forma (por exemplo, usando o site da empresa para corrigir um problema), deve acionar a nova verificação alterando o URL no objeto Account para qualquer outro valor e, em seguida, alterando-o imediatamente de volta.

Você não pode usar a API para resolver todos os problemas relacionados ao URL. Alguns erros de verificação de URL exigem informações como acessar o site da conta conectada ou confirmar que a conta está isenta de requisitos de URL. Esses problemas exigem que você ou sua conta conectada forneça informações complementares.

Se não conseguir resolver o problema, encaminhe sua conta conectada para entrar em contato com o suporte da Stripe.

Consulte a tabela a seguir para resolver erros de verificação de URL.

Lidar com os requisitos de vida útil

Uma conta pode ter um ou mais objetos Person com um requisito de proof_of_liveness. Um requisito de proof_of_liveness pode exigir a cobrança 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 um sistema de onboarding hospedado ou incorporado pela Stripe para atender a todas as variações do requisito de 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

Dependendo dos dados de identificação verificados para uma conta, podemos solicitar que você carregue um ou mais documentos. Os documentos necessários aparecem no hash de requisitos no objeto Account.

Você deve carregar os documentos que aparecem em requirements.currently_due:

• person.verification.document: carregue uma digitalização ou foto colorida de uma forma de identificação aceitável.
• person.verification.additional_document: carregue 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.
• empresa.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.

Quando requirements.alternatives.alternative_fields_due contém requisitos de verification.document, eles podem ser usados como uma alternativa para requirements.alternatives.original_fields_due.

Por questões de segurança, a Stripe não aceita documentos de identificação por e-mail. Enviar um documento é um processo feito em duas etapas:

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

Carregar um arquivo

Para carregar um arquivo, chame a API Files para criar um arquivo.

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

Envie os dados do arquivo no parâmetro file e defina o parâmetro purpose de acordo com o objeto Account ou Person ao qual o documento será vinculado. Consulte a documentação da API para identificar o valor correto para o campo de finalidade.

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"

A seguinte 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

Após fazer o upload do arquivo e receber o token correspondente, atualize o objeto Account ou Person e informe o ID do arquivo no campo apropriado.

O exemplo a seguir é para um documento de identificação oficial:

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

O exemplo a seguir é para um documento da empresa:

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

Esta atualização altera verification.status para pending. Se mais pessoas precisarem ser verificadas, 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 contém um erro com um código e uma descrição que descrevem a causa. A descrição é uma mensagem de linguagem simples não localizada, como “A imagem fornecida não é legível”, que você pode apresentar ao usuário da conta. O valor do código é uma string, como verification_document_not_readable, que você pode usar para traduzir 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.

Cobrança de documentos hospedados com o Stripe Identity

Você pode usar Stripe Identity para cumprir umperson.verification.document requisito ao recolher um documento e anexá-lo diretamente à conta. No entanto, você não pode usar o Stripe Identity para cumprirperson.verification.additional_document ou requisitos de company.verification.document.

Crie uma VerificationSession. Defina o parâmetro related_person para vincular os dados de verificação coletados ao objeto Person que exige o document, conforme ilustrado no exemplo a seguir:

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

Depois de criar a VerificationSession, use o cliente_secret retornado para mostrar o modal Identity ao usuário ou redirecionar o usuário para o URL. A conclusão da verificação atualiza automaticamente a conta.

Enviamos um evento account.updated ao endpoint de webhook quando a conta concluir a verificação de identidade e atualizar os dados.

Gerenciamento de requisitos estabelecidos por formulário ou suporte

A Stripe informa os requisitos de risco e conformidade no hash requisitos. Esses requisitos têm o formato <id>.<requirement_description>.<resolution_path>.

• id: identifica exclusivamente as informações necessárias à Stripe ou aos nossos parceiros financeiros. Esse identificador é sempre prefixo com interv_ para indicar que é um requisito de verificação de risco.
• requirement_description: descreve especificamente as informações necessárias para preencher o requisito, como identity_verification, rejection_appeal e assim por diante.
• resolution_path: especifica como você ou sua conta conectada pode fornecer as informações solicitadas:
  • challenge: a conta conectada deve responder diretamente às solicitações de desafio, que geralmente exigem informações confidenciais (como uma conta bancária) ou informações que somente o proprietário da conta pode fornecer (como uma selfie).
  • form: a conta conectada pode preencher solicitações de formulário, ou você pode preenchê-las em nome dela.
  • suporte: o requisito não pode ser executado diretamente. Entre em contato 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:

• Conecte componentes integrados do Connect: conecte componentes integrados do Connect ao seu site e direcione os usuários para o componente integrado da conta de onboarding, onde eles serão solicitados a concluir os pedidos pendentes na sua interface. Você também pode usar o componente integrado do banner de notificação para informar os usuários sobre quaisquer requisitos pendentes.
• Onboarding hospedado pela Stripe: gere links para direcionar suas contas conectadas a concluir os requisitos pendentes automaticamente por meio de links de conta ou manualmente em seu Dashboard da plataforma.
• Concluir em nome das suas contas: use o Dashboard da plataforma para identificar e concluir requisitos de risco baseados em formulário em nome das contas conectadas.

A tabela a seguir fornece mais informações sobre os requisitos relacionados a riscos e conformidade.