Handling verification with the API

Platforms with accounts created using the API can provide Stripe with necessary information about their users for Know Your Customer (KYC) purposes. Platforms can use Connect Onboarding to collect KYC information, or use the Accounts and Persons APIs to provide Stripe with required information. We’ll then perform verification, asking for more information when needed.

The rest of this page goes through how platforms:

• Discover verification requirements for a connected account
• Provide the necessary information to Stripe

Platforms that use Custom connected accounts can also read Identity Verification for Custom Accounts to learn about the verification flow options, how the API fields translate to both companies and individuals, and how to localize information requests.

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, you’ll need to be set up 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. If additional information is required, obtain it 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 has already been verified, you don’t need to provide it again in subsequent updates).

Change information after verification

After an individual or company is verified, you may 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 via 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: Fields that you might need to collect, assuming all thresholds are reached. As they become required, they appear in currently_due and set the current_deadline. All required information starts in this array.
• currently_due: Fields that you must collect by the current_deadline for the connected account to remain enabled. currently_due is a subset of eventually_due.
• past_due: Fields you didn’t submit by the deadline, which disabled the connected account. past_due is a subset of currently_due.
• errors: The list of reasons why a particular field in currently_due must be collected again because validation or verification failed.
• disabled_reason: Describes why the connected account isn’t enabled.
• current_deadline: Date by which the fields in currently_due must be collected to keep the account enabled. The account may be disabled sooner if the next threshold is reached before the currently_due fields are collected.
• pending_verification: Fields that may become required depending on the results of verification or review. Is an empty array unless a verification is pending. If verification fails, fields in pending_verification move to eventually_due, currently_due, or past_due.

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": [
          "external_account",
          "individual.dob.day",
          "individual.dob.month",
          "individual.dob.year",
          "individual.first_name",
          "individual.last_name",
          "tos_acceptance.date",
          "tos_acceptance.ip"
      ],
      "eventually_due": [
          "external_account",
          "individual.address.city",
          "individual.address.line1",
          "individual.address.postal_code",
          "individual.address.state",
          "individual.dob.day",
          "individual.dob.month",
          "individual.dob.year",
          "individual.first_name",
          "individual.last_name",
          "individual.ssn_last_4",
          "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, there can be other consequences 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.

• Standard connected accounts can access additional information (if available) on their Dashboard.
• Platforms in any Connect configuration can navigate to Accounts to review to understand 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 may verify that the provided business URL is valid, reachable, and includes information about the business. To retrieve the status of verification information regarding a business, utilize the requirements on the Account object.

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:

Person information

During the verification process, information about the persons associated with an account needs to be collected. If you onboard:

• Only companies, use the Persons API to collect this information.
• Only individuals, 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 collect this information. This way you collect information in the same manner regardless of business type.

To retrieve the status of verification information regarding a person, utilize the Person object’s verification subhash:

{
  "id": 
"{{PERSON_ID}}",
  "object": "person",
  ...
  "verification": {
    "document": null
  }
  ...
}

You can look up the definition for each verification attribute on the Person object. The two attributes worth noting are status and details.

status indicates the state of verification for the person:

• pending: Stripe is currently trying to verify this entity.
• unverified: Stripe isn’t able to verify this entity right now, either because verification has failed or because we don’t have enough information to attempt verification.
• verified: Stripe has successfully verified this entity.

Note that an unverified status isn’t necessarily an urgent issue, but it does mean that Stripe might request more information soon.

The details attribute provides an explanation for the current status.

Below is a list of errors related to person verification:

Acceptable verification documents by country

Below is a listing of documents that Stripe can accept as proof of identity, address, and entity for each country Stripe supports.

Some forms of documentation require scans of both the front and back of the document. For these, use the document_back parameter to provide the back of the document. Unless explicitly noted, only a scan of the front of the document is required.

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, utilize 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

Many complications with the verification process involve the uploaded document itself. To help you recognize and handle the most common problems, the table below lists possible values for the error code (in the requirements.errors array) and the likely resolutions for each error.

Below is a list of errors related to document upload:

Below is a list of errors related to identity verification:

Below is a list of errors related to business verification:

Handle URL verification errors

URLs for e-commerce businesses need to conform to certain card network standards. See the website checklist for best practices for URLs and common elements for e-commerce businesses. Stripe conducts a number of verifications for URL integrity. There are two methods to resolve URL integrity errors:

• Using the API - Use the error code to handle the URL issue. If you need to update the URL, use the Update Account API, which also causes Stripe to verify the updated URL. If you don’t have to update the URL, Stripe still needs to clear the error by verifying the URL again. After you make any other required updates, trigger reverification by using the API to change the URL to any other value and then change it back.
• Using the Dashboard - Platforms can use the Accounts to review page in the Stripe Dashboard to understand the impact to their connected accounts and what actions to take.

Not all URL-related issues can be resolved using the API. Certain types of URL integrity errors require additional information on how to access the connected account’s webpage or to attest that the account is exempt from URL requirements. These types of issues require that you or your connected account provide supplemental information. Visit your Accounts to review page to resolve the error, or direct your connected account to contact Stripe Support.

To help you handle the most common errors associated with the business_profile.url field, the following table lists the related error codes (in the requirements.errors array) and possible resolutions.

Handle identity verification

You can respond in two ways to an identity verification change. The first is to perform an Update Account call, correcting or adding information.

Secondarily, we might ask you to upload a document. Depending on how much of the user’s information Stripe has been able to verify, we might require three different types of document uploads. You can determine what documents to upload based on the fields listed in requirements.currently_due:

• 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
• For identity documents, can be JPG or PNG format
• For address or legal entity documents, can be JPG, PNG, or PDF format

Pass the file data in the file parameter and set the purpose parameter to identity_document:

curl https://files.stripe.com/v1/files \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -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
}

You may then 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, provide the file ID using the appropriate field in your Update Account call.

Below is an example for an ID document:

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons/
{{PERSON_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

If the color scan or photo of the ID passes Stripe’s checks, the document requirement is removed from requirements.currently_due. Satisfying all verification requirements for the person or company triggers an account.updated webhook notification signaling the verification process is complete.

Verification can take Stripe from a few minutes, to a couple business days to complete, depending on how readable the provided image is.

If the verification attempt fails, the requirements.errors array contains an error stating the cause. The error[reason], such as “The image supplied was not readable,” is safe to present to your user, but is not localized. The response also contains an error[code] value, such as verification_document_not_readable, which you can use to localize errors for your users. Upon failure, requirements.currently_due indicates that a new ID upload is required. If the deadline for verification is near, requirements.current_deadline might also be populated with a date. Verification failure also triggers an account.updated webhook notification.