Handle verification with the API

Connect platforms that onboard connected accounts using the API must provide Stripe with required information for Know Your Customer (KYC) purposes and to enable account capabilities. They must collect the information themselves and use the Accounts and Persons APIs to provide it to Stripe. We then verify the information, asking for more details when needed.

Responsible platforms must also monitor their connected accounts’ requirement statuses and handle any updates in a timely manner.

Verification process

Before enabling charges and payouts for a connected account, Stripe needs certain information that varies based on:

• The origin country of the connected accounts
• The service agreement type applicable to the connected accounts
• The capabilities requested for the connected accounts
• The business_type (for example, individual or company) and company.structure (for example, public_corporation or private_partnership)

Platforms must choose the proper onboarding flow for their business and connected accounts to meet the KYC requirements. That means providing all the requisite information up front or incrementally. Either way, set up your integration to watch for and respond to requests from Stripe.

1. Establish a Connect webhook URL in your webhook settings to watch for activity, especially account.updated events. When using the Persons API, also watch for person.updated events.
2. Immediately after creating an account, check the Account object’s requirements.currently_due attribute for additional requirements. Obtain any required information from the connected account and update the Account. As long as requirements.currently_due isn’t empty, the Account has outstanding requirements that might restrict its capabilities.
3. Continue watching for account.updated event notifications to see if the requirements hash changes, and ask the connected account for additional information as needed.

When you provide additional information, you don’t need to resubmit previously verified details. For example, if the dob is already verified, you don’t need to provide it again unless it changes.

Stripe risk review requirements

Stripe risk reviews of a connected account can add extra requirements, which you can’t provide using the API. You can take action in your Dashboard, or the connected account can provide them through a Connect embedded component, Stripe-hosted onboarding, or remediation link.

Determine if verification is needed

The charges_enabled and payouts_enabled attributes on an Account object indicate whether it can create charges and accept payouts.

If either of those attributes is false, check the Account’s requirements hash to determine what information is needed to enable charges and payouts.

The requirements hash contains the following properties:

The example below shows what the requirements hash might look like for an account that has information that’s currently_due, information that’s eventually_due, and information that raised verification errors.

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

If requirements.currently_due contains entries, check requirements.current_deadline, which is a Unix timestamp. Stripe typically disables payouts on the account if we don’t receive the information by the current_deadline. However, other consequences might apply in some situations. For example, if payouts are already disabled and the account is unresponsive to our inquiries, Stripe might also disable the ability to process charges.

Separately, the requirements.disabled_reason property can contain a string describing why the account has certain capabilities disabled. In some situations, platforms and connected accounts can submit a form to resolve or appeal the reason.

• Connected accounts with access to the full Stripe Dashboard, including Standard accounts, can access additional information (if available) in the Dashboard.
• Platforms can look up an account’s disabled_reason on the Connected accounts page. You might be able to provide additional information on behalf of your connected accounts. If the disabled reason is associated with an appeal, you can generate a link to a form for the account to resolve the appeal.

Validation and verification errors

The Account object includes a requirements.errors array that explains why the validation or verification requirements haven’t been met. You must fulfill these requirements in order to enable the account’s capabilities.

The errors array has the following attributes:

The following example shows an errors array for an account with requirements that are currently_due, the reason why the submitted information can’t be used to enable the account, and how to resolve the 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.",
          }
      ]
  },
  ...
}

If verification or validation is unsuccessful, requirements can reappear in currently_due, alternative_fields_due, or eventually_due with error information. To receive notification of these requirements, set a Connect webhook to listen to the account.updated event.

Business information

Stripe verifies all information submitted about a business. For example, we might verify that the business URL is valid, is reachable, and includes information about the business. To check the verification status, you can retrieve the requirements hash on the Account object.

The following errors relate to business information verification:

See Handle URL verification errors to resolve the following URL errors:

• 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

Business representatives

You must collect and submit information about the people associated with a connected account. The process depends on whether your connected accounts are companies, individuals, or both.

For companies, use the Persons API to add the information to a Person object associated with the Account object. To add documents to the verification hash on the Person object, first use the Files API to upload the document files to Stripe’s servers.

For individuals, you can either create a Person or add the information to the individual hash on the Account object.

If your connected accounts include both companies and individuals, create Person objects so you can use the same process for all of them.

To check the verification status of an Account, you can retrieve its requirements hash.

The following errors relate to person verification:

Acceptable verification documents

The types of identity documents that Stripe accepts for connected accounts vary by country and are the same as for other Stripe accounts.

Company information

During the verification process, you might need to collect information about the company for an account.

To check the verification status, you can retrieve the company.verification subhash on the Account object.

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

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

Statement descriptors

Stripe validates the statement descriptor and statement descriptor prefix when you set them on an Account. For example, we might verify that the first 22 characters, which are provided to the card networks, match the description of the business. We check whether they’re a close match of the Account’s business_profile.name, business_profile.url, or the name of the company or individual.

To check the statement descriptor verification status, you can retrieve the requirements hash on the Account object.

The following errors relate to statement descriptor verification:

Handle document verification problems

Refer to the following table to resolve common requirement verification errors related to uploaded document files.

If verification fails, don’t resubmit the same file. Duplicate uploads fail automatically.

Handle URL verification errors

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).

URLs for e-commerce businesses must conform to certain card network standards. In order to comply with these standards, Stripe conducts a number of verifications when reviewing URLs. Learn about the best practices for URLs and common elements for e-commerce businesses.

In many cases, you can resolve URL verification errors by doing either of the following:

• Generating a remediation link from your platform Dashboard.
• Updating the business_profile.url on the Account object.

If you resolve the error another way (for example, by using the company website to fix a problem), you must trigger re-verification by changing the URL on the Account object to any other value, then immediately changing it back.

You can’t use the API to resolve all URL-related issues. Certain URL verification errors require information such as how to access the connected account’s website or to attest that the account is exempt from URL requirements. These issues require you or your connected account to provide supplemental information.

If you can’t resolve the issue, direct your connected account to contact Stripe support.

Refer to the following table to resolve URL verification errors.

Handle liveness requirements

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_CGGvfNiIPwLXiDwaOfZ3oX6Y
:" \
  -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

Handle identity verification

Depending on the identity information we have verified for an account, we might ask you to upload one or more documents. The required documents appear in the requirements hash on the Account object.

You must upload the documents that appear in requirements.currently_due:

• person.verification.document: Upload a color scan or photo of an acceptable form of ID.
• person.verification.additional_document: Upload a color scan or photo of a document that verifies the user’s address, such as a utility bill.
• company.verification.document: Upload a proof of entity document that establishes the business entity ID number, such as the company’s articles of incorporation.

If requirements.alternatives.alternative_fields_due contains verification.document requirements, you can use them as an alternative to requirements.alternatives.original_fields_due.

For security reasons, Stripe doesn’t accept ID documents through email. Uploading a document is a two-step process:

1. Upload the file to Stripe.
2. Attach the file to the account.

Upload a file

To upload a file, call the Files API to create a File.

The uploaded file must meet these requirements:

• Color image (8,000 pixels by 8,000 pixels or smaller)
• 10 MB or less
• Identity documents are JPG or PNG format
• Address or legal entity documents are JPG, PNG, or PDF format

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_CGGvfNiIPwLXiDwaOfZ3oX6Y
: \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" \
  -F "purpose"="identity_document" \
  -F "file"="@/path/to/a/file"

The following request uploads the file and returns a token:

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

Use the token’s id value to attach the file to a connected account for identity verification.

Attach the file

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.

The following example is for a government-issued ID document:

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

The following example is for a company document:

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

This update changes verification.status to pending. If an additional person needs verification, use the Persons API to update them.

Confirm ID verification

Satisfying all identity verification requirements for a person or company triggers a v2.core.account_person.updated or v2.core.account[identity].updated webhook notification, signaling that the verification process is complete.

Stripe can take anywhere from a few minutes to a few business days to verify an image, depending on its readability.

If the verification attempt fails, the associated requirement entry contains an error with a code and description describing the cause. The description is a non-localized plain language message, such as “The image supplied isn’t readable,” that you can present to your account user. The code value is a string, such as verification_document_not_readable, that you can use to localize error messages for your account users.

Verification failure also triggers a v2.core.account_person.updated or v2.core.account[identity].updated webhook notification.

Hosted document collection with Stripe Identity

You can use Stripe Identity to fulfill a person.verification.document requirement by collecting a document and attaching it directly to the account. However, you can’t use Stripe Identity to fulfill person.verification.additional_document or company.verification.document requirements.

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

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

After you create the VerificationSession, use the returned client_secret to show the Identity modal to the user or redirect the user to the url. Verification completion automatically updates the account.

We send an account.updated event to your webhook endpoint when the account completes the identity check and updates their information.

Handle form or support-based requirements

Stripe reports risk and compliance requirements in the requirements hash. These requirements have the <id>.<requirement_description>.<resolution_path> format.

• id: Uniquely identifies information that Stripe or our financial partners need. This identifier is always prefixed with interv_ to indicate that it’s a risk verification requirement.
• requirement_description: Specifically describes the information needed to complete the requirement, such as identity_verification, rejection_appeal, and so on.
• resolution_path: Specifies how you or your connected account can provide the requested information:
  • challenge: The connected account must respond directly to challenge prompts, which often require sensitive information (such as a bank account) or information that only the account owner can provide (such as a selfie).
  • form: The connected account can complete form requests, or you can complete them on their behalf.
  • support: The requirement isn’t directly actionable. Contact Stripe support.

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

After satisfying a resolution path, the value of the requirement’s resolution path might change to support and the requirement also appears in the pending_verification section of the requirements hash. Stripe verifies the submitted information and either dismisses the requirement as resolved or posts a new currently due requirement.

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

You can remediate risk and compliance requirements in any of the following ways, depending on the type of requirement:

• Connect embedded components: Embed Connect components into your website, and direct your users to the account onboarding embedded component, where they’re prompted to complete outstanding requirements in your UI. Alternatively, use the notification banner embedded component to prompt your users for any outstanding requirements.
• Stripe hosted onboarding: Generate links to direct your connected accounts to complete outstanding requirements programmatically through account links or manually in your platform Dashboard.
• Complete on behalf of your accounts: Use your platform Dashboard to identify and complete form-based risk requirements from connected account details on behalf of your accounts.

The following table provides more information about risk- and compliance-related requirements.