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.

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 need to choose the proper onboarding flow for their business and users to meet the KYC requirements. Broadly speaking, this means providing all the requisite information upfront 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 events of the account.updated type. When using the Persons API, you should also watch for person.updated events.
2. Immediately after creating an account, check the Account object’s requirements.currently_due attribute for any additional requirements. Obtain any required information from the user and update the connected account.
3. Continue watching for account.updated event notifications to see if the requirements hash changes, and reach out to your user for additional information as needed.

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

Change information after verification

After an individual or company is verified, you can change some of their information, with limitations. See the Update Account API for limitations based on the configuration of the connected account. Contact support to make changes outside of these limitations.

Determine if verification is needed

When you receive an account.updated event to your webhook or fetch an account with the API, you receive an Account object. The Account object’s charges_enabled and payouts_enabled attributes indicate whether the account can create charges and accept payouts.

The Account object has a requirements hash, representing the requirements needed to verify the account.

The requirements hash has the following arrays:

• eventually_due: Requirements that you might need to collect, depending on whether the corresponding thresholds are reached. After a requirement becomes required, it also appears in the currently_due list. If a requirement becomes required and its due date is before the existing current_deadline, the current_deadline changes to the corresponding threshold’s enforcement date.
• currently_due: Requirements that you must collect by the current_deadline for the Account to remain active. currently_due is a subset of eventually_due.
• past_due: Requirements that have disabled capabilities because they weren’t verified before the current_deadline. past_due is a subset of currently_due.
• errors: Details about validation and verification failures that require particular requirements in currently_due or past_due to be collected again.
  • requirement: Identifies the requirement corresponding to the error.
  • code: An enum value describing why the requirement is invalid or can’t be verified.
  • reason: An English message describing the error in more detail. The reason string can also suggest how to resolve the error.
• disabled_reason: Describes why the Account isn’t enabled and why it can’t process charges or transfers.
• current_deadline: Date by which requirements in currently_due must be collected 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: Requirements that might become required, depending on the results of verification or review. It’s an empty array unless an asynchronous verification is pending. Unsuccessful verification moves a requirement to eventually_due, currently_due, or past_due. A requirement subject to both failed and pending verifications can also remain in pending_verification.

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

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

If requirements.currently_due contains entries, check requirements.current_deadline. The current_deadline is a Unix timestamp identifying when information is needed. Usually, if Stripe doesn’t receive the information by the current_deadline, payouts on the account are disabled. 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 have a value. The value is a string describing the reason why this account is unable to make payouts or charges. In some instances, 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 on the Connected accounts page to determine an account’s disabled_reason. 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, which are needed to enable your account and capabilities. The errors array has the following attributes:

• requirement: Specifies which information from the currently_due array is needed.
• code: Indicates the type of error that occurred. See the API reference for all possible error codes.
• reason: Explains why the error occurred and how to resolve the error.

Below is an example that shows what the errors array might look like for an account with requirements that are currently_due. The example shows the reason why the submitted information can’t be used to enable the account, and how to resolve the error. If verification or validation is unsuccessful, requirements can reappear in currently_due with error information. Set a Connect webhook to receive the account.updated event to receive these updates.

{
  "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 but no requirements are currently due, a webhook triggers indicating that required information is eventually due.

Business information

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’s requirements hash.

Below is a list of errors related to business information verification:

Statement descriptors

Stripe validates the statement descriptor and statement descriptor prefix when set on an account. For example, Stripe might verify that the provided statement descriptor matches the description of the business. When validating the statement descriptor matches the business description, Stripe uses the first 22 characters of the statement descriptor, representing the part that is provided to the card networks. A business description is a close match of the account’s business_profile.name, business_profile.url, or the name of the company or individual.

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:

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 or individuals:

• Companies only: Use the Persons API to add the information to a Person associated with the Account.
• Individuals only: You can use the Persons API or the individual hash on the Account object.
• A combination of individuals and companies: Use the Persons API to add the information to a Person associated with the account. That lets you use the same process for all of your connected accounts, regardless of their type.

To retrieve the status of verification information regarding a person, use the requirements hash.

Below is a list of errors related to person verification:

Acceptable verification documents by country

To learn about specific document requirements, view Acceptable verification documents by country.

Company information

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

To retrieve the status of verification information regarding an account’s company, use the Account’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.

Handle document verification problems

Problems with identity documents, either with uploaded files themselves or with using them to validate other information, cause many requirement verification errors. To help you recognize and handle the most common problems, the tables below list requirement error code values related to document issues and provide guidance for resolving them.

The following errors relate to uploaded document files:

THe following errors relate to identity verification:

The following errors relate to business verification:

The following errors relate to relationship verification:

Handle URL verification errors

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

In many cases, you can resolve business URL verification errors by generating a remediation link from your platform Dashboard. Otherwise, update the Account’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 to any other value, then immediately changing it back.

Not all URL-related issues can be resolved using the API. Certain types of URL verification errors require additional information on how to access the connected account’s website or to attest that the account is exempt from URL requirements. These types of 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.

To help you recognize and handle the most common problems, the following table lists requirement error code values related to issues with the business URL and provides guidance for resolving them.

Handle liveness requirements

An account can have one or more Persons 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

Handle identity verification

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’s requirements hash.

The following entries in requirements.currently_due identify documents that you must upload:

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

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, use the Create File API by using a POST to send the file data as part of a multipart/form-data request.

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

This 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 and provide the file ID in the appropriate parameter.

Below is an example for an ID document:

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

Below is an example for a company document:

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

This update changes verification.status to pending. If an additional person needs to be verified, 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 contains a human-readable message such as “The image supplied isn’t readable,” which is safe to present to your account user but isn’t localized. The code value is a string such as verification_document_not_readable, which 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.

Handle risk verifications

Stripe reports risk and compliance requirements in the accounts.requirements attribute. These requirements follow the schema: <id>.<requirement_description>.<resolution_path>:

• id uniquely identifies information needed by Stripe or our financial partners. This identifier is always prefixed with interv_ to indicate that it is 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: Connected accounts must directly respond to challenge prompts. They often require sensitive information, such as a bank account, or information that only the account owner can provide, such as a selfie.
  • form: Connected accounts 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: You can embed Connect components directly into your website. When a requirement surfaces, direct your users to the account onboarding embedded component, where they’re prompted to complete outstanding requirements directly in your UI. Alternatively, use the Notification banner embedded component to prompt your users for any outstanding requirements.
• Stripe hosted onboarding: You can 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: You can use your platform Dashboard to identify and complete form-based risk requirements from connected account detail on behalf of your accounts.

The following table provides more detail about possible descriptions of risk- and compliance-related requirements.