Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
Get started
Collect payments then pay out
Enable other businesses to accept payments directly
Pay out money
Explore Connect
Onboard your accounts
Choose your account type
Standard
Express
Custom
Onboard accounts
Update accounts
Handle verification
Handle verification with the API
Required info
Future requirements
Service agreement types
Account capabilities
Additional verifications
Update verified info
Accept payments
Create a charge
Create a payments page
Create payment links with Connect
Connect integration guide
Automatic payment methods
Set statement descriptors
Connect platforms using the Payment Methods API
Create subscriptions
Create invoices
Debit connected accounts
Pay out
Set bank and debit card payouts
Bank accounts
Manage payout schedule
Manual payouts
Payout reversals
Instant Payouts
Cross-border payouts
Crypto payouts
Manage funds
Add money to your platform balance
Account balance
Handle multiple currencies
Manage accounts
Best practices
Listen for updates
Dashboard account management
Platform controls for Standard accounts
Make API calls for connected accounts
Set MCCs
Testing
Manage tax forms
Overview
Get started with tax reporting
Tax form settings
Calculation methods
File tax forms
File tax forms with states
Update tax forms
Deliver tax forms
Correct tax forms
Split tax forms
Tax year changeover
Testing
No-code options
Connect
·
HomePaymentsMultiparty paymentsCustom

Handling verification with the API

Learn how Connect platforms can use webhooks and the API to handle identity and business verification.

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:

  • Know when identity or business verification is needed
  • Provide the necessary information to Stripe

Platforms that use Custom connected accounts should also read the Identity Verification for Custom Accounts guide 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 country the connected account is in.
  • The capabilities the connected account needs.
  • Whether the business entity is a company or an individual.

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

When requirements[currently_due] is not empty, additional information is required. Connected accounts may be blocked from creating charges, receiving payouts, or performing certain tasks if you don’t provide this information in a timely manner.

Changing information after verification

After an individual or company is verified, you may change some of their information, with limitations. You will need to contact support to make changes outside of these limitations.

Determining if identity or business verification is needed

When you receive an account.updated webhook notification or fetch an account via the API, you receive an Account object. The Account object’s charges_enabled and payouts_enabled 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: Information in this array isn’t needed immediately, but it will be when certain thresholds are hit. All required information starts in this array.
  • currently_due: Information in this array needs to be collected by the current_deadline and is a subset of eventually_due.
  • past_due: Information in this array means the account is disabled because the required information wasn’t collected. past_due is a subset of currently_due.

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

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

If requirements[currently_due] isn’t an empty array, requirements[current_deadline] might be set. This is a Unix timestamp identifying when the 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 for rarer situations. For example, if payouts are already disabled and our inquiries aren’t being responded to within a reasonable period of time, Stripe might also disable the ability to process charges.

Separately, the requirements[disabled_reason] property might also be set. This is a string describing the reason why this account is unable to make payouts or charges. The reason can fall into several categories.

ReasonMeaning
action_required.requested_capabilitiesYou need to request capabilities for the connected account. For details, see Request and unrequest capabilities.
requirements.past_dueAdditional verification information is required to enable payout or charge capabilities on this account.
requirements.pending_verificationStripe is currently verifying information on the connected account.
rejected.fraudAccount is rejected due to suspected fraud or illegal activity.
rejected.terms_of_serviceAccount is rejected due to suspected terms of service violations.
rejected.listedAccount is rejected because it’s on a third-party prohibited persons or companies list (such as financial services provider or government).
rejected.otherAccount is rejected for another reason.
listedAccount might be on a prohibited persons or companies list (Stripe will investigate and either reject or reinstate the account appropriately).
under_reviewAccount is under review by Stripe.
otherAccount isn’t rejected but is disabled for another reason while being reviewed.

Validation and verification errors

The Account object includes an 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 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 that might be delivered asynchronously to you through webhooks.

{ "requirements": { "current_deadline": 1234567800, "currently_due": [ "company.name", "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.

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.

You can use a verification subhash to help manage identity verification on both the Person object and the individual hash (you should also watch for person.updated events so you know when there are changes).

{ "verification": { "details": null, "details_code": null, "document": null, "additional_document": null, "status": "unverified" }, ... }

The Account object has a verification subhash as well:

{ "verification": { "document": null } }

You can look up the definition for each verification attribute on the Person object or the Account object, but the two attributes worth noting now are status and details.

status indicates the current verification state for the person and has three possible values.

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

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.

Acceptable identity documents vary by country, however, a passport scan for identity verification is always acceptable and is preferred.

Acceptable forms of identification:

  • Passport
  • Driving License
  • Social Security Card

Handling 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:

ErrorResolution
verification_document_corrupt verification_document_failed_copy verification_document_failed_greyscale verification_document_incomplete verification_document_not_readable verification_document_not_uploaded verification_document_not_signed verification_document_missing_back verification_document_missing_front verification_document_too_largeThe upload failed due to a problem with the file itself. Ask your user to provide a new file that meets 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
  • For legal entity documents, must include all pages
  • Must not be password protected
verification_document_country_not_supported verification_document_invalid verification_document_type_not_supportedThe provided file is not an acceptable form of ID from a supported country, or is not a type of legal entity document that is expected. Ask your user to provide a new file that meets that requirement. For a list, see Acceptable ID types by country.
verification_failed_other verification_document_failed_otherYour team may contact Stripe to learn more about why identity verification failed.
verification_document_expired verification_document_issue_or_expiry_date_missingThe issue or expiry date is missing on the document, or the document is expired. If it’s an identity document, its expiration date must be after the date the document was submitted. If it’s an address document, the issue date must be within the last six months.

Below is a list of errors related to identity verification:

ErrorResolution
verification_failed_keyed_identityThe name on the account couldn’t be verified. Ask your user to verify that they have provided their full legal name and to also provide a photo ID matching that name.
verification_document_name_mismatch verification_document_dob_mismatch verification_document_address_mismatch verification_document_id_number_mismatch verification_document_photo_mismatchThe information on the ID document doesn’t match the information provided by the user. Ask your user to verify and correct the provided information on the account.
verification_document_fraudulent verification_document_manipulatedThe document might have been altered so it could not be verified. Your team may contact Stripe to learn more.

Below is a list of errors related to business verification:

ErrorResolution
verification_failed_keyed_match verification_failed_document_matchThe information on the account couldn’t be verified. Your user can either upload a document to confirm their account details, or update their information on their account.
verification_failed_tax_id_not_issued verification_failed_tax_id_matchThe information that your user provided couldn’t be verified with the IRS. Ask your user to correct any possible errors in the company name or tax ID, or upload a document that contains those fields. (U.S. only)
verification_failed_id_number_match verification_failed_name_match verification_failed_address_matchThe information on the document doesn’t match the information provided by the user. Ask your user to verify and correct the provided information on the account, or upload a document with information that matches the account.
verification_document_address_missing verification_document_id_number_missing verification_document_name_missingThe uploaded document is missing a required field. Ask your user to upload another document that contains the missing field.

Don’t resubmit a file that previously failed. Duplicate uploads immediately trigger an error and aren’t rechecked.

Handling 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

For security reasons, Stripe doesn’t accept copies of IDs sent by email.

Uploading a file

To upload a file, POST it as part of a multipart/form-data request to https://files.stripe.com/v1/files.

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 in the file parameter and set the purpose parameter to identity_document:

Terminal
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_5dtoJkOhAxrMWb", "created": 1403047735, "size": 4908 }

You may then use the token’s id value to attach the file to a connected account for identity verification.

Attaching 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_5dtoJkOhAxrMWb

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_5dtoJkOhAxrMWb

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

Confirming ID verification

If the color scan or photo of the ID passes Stripe’s checks, the document requirement is removed from requirements[currently_due]. If you’ve satisfied all verification requirements for the person or company, an account.updated webhook notification is sent when 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] is safe to present to your user, such as “The image supplied was not readable”. In addition, the response contains an error[code] value, such as verification_document_not_readable. Upon failure, requirements[currently_due] indicates that a new ID upload is required. If the deadline for verification is near, requirements[current_deadline] may also be populated with a date. Again, an account.updated webhook notification is sent as well.

See also

  • Updating Accounts
  • File Upload Guide
  • Identity Verification for Custom Accounts
  • Account Tokens
  • Testing Custom Account Identity Verification
  • Required Verification Information
Was this page helpful?
Questions? Contact us.
View developer tutorials on YouTube.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Verification process
Determining if identity or business verification is needed
Validation and verification errors
Person information
Acceptable verification documents by country
Handling document verification problems
Handling identity verification
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to Stripe docs and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$