Verification Best Practices

You are required to collect identity verification information from your connected accounts. Stripe uses this information to verify connected-account identities. This ensures Stripe complies with know your customer KYC and anti-money laundering regulations. Verification flows vary depending on your business type (B2B or B2C), and they should be taken into consideration when you build your user experience. Regardless of your business type, you should use account tokens to collect this information.

While collecting verification information, have connected accounts accept Stripe’s terms of service and submit their bank account details as well. This information isn’t required for identity verification, but without it, transfers are blocked even if verification succeeds.

If you haven’t read Identity Verification for Custom Accounts and checked the verification requirements for your country yet, we recommend you review those before reading this document.

B2B approach

For B2B platforms, we recommend you submit all required verification information upfront. This means your seller account creation flow needs to have all the required fields. We recommend this for a few reasons:

  • You may already have this information
  • It reduces the chance you’ll need to contact connected accounts for information after they’ve onboarded
  • When connected accounts hit our volume threshold, you won’t have to request more verification information

Upfront onboarding

With upfront onboarding, your seller account creation flow gathers all the required fields. If possible, gathering additional verification requirements is recommended. We don’t run credit checks on company representatives that submit verification information. Sometimes company representatives are concerned about this, so you may want to inform them that this won’t happen when they submit their information.

After your form is created, your engineering team can build webhook endpoints to monitor the verification process. Monitoring this process lets you ensure accounts are verified, and helps you resolve issues quickly. Some examples include:

  1. Checking the legal_entity verification status is verified.
  2. Tracking the fields_needed parameter for information that needs to be resubmitted. If this field is empty, no additional information is required.
  3. Tracking account.updated for changes to verification status.

In live mode, legal_entity: verified is returned if the information passes Stripe’s automated checks. If an ID is uploaded and fails automated verification checks, the status may remain pending for up to 48 hours while the account is manually reviewed. To track verification status, use a webhook to monitor the account.updated event.

When uploading photo ID documents, legal_entity.verification.document is present in fields_needed until the account is updated with a file ID. If photo ID verification fails, legal_entity.verification.document is returned in fields_needed again.

If you want to view what connected accounts can do in their current verification state, you can check charges_enabled and transfers_enabled. These don’t reflect the current verification status, but they do provide additional information on your connected accounts.

B2C approach

B2C platforms often use a lightweight signup process that breaks up the verification process, also known as incremental onboarding. This is because their connected accounts generally don’t hit volume thresholds as fast, and a simpler signup flow can improve conversion. Connected accounts can get started with just an email address and a country. As more funds are processed, additional verification is required.

Incremental onboarding

When using incremental onboarding, you should build notifications that prompt users for more verification information. There’s a technical recipe you can share with your engineering team to build these notifications. In these communications, you should explain that additional verification information is needed, even though the user already submitted some. Many users assume their account is fully active after submitting the initial signup information and are confused later when more information is needed.

Submitting verification information

Stripe automates the verification process as much as possible. However, it’s helpful to understand why we need certain information, how to request it from users, and what to do if automatic verification checks fail. Your engineering team should read Handling Identity Verification with the API to understand what to build.

Verification information, including photo IDs and personal ID numbers (e.g., SSNs) should be submitted using the API. Your developers should build a self-serve form that users fill out. Make sure personally identifiable information (PII), like SSNs is tokenized.

Connected accounts should always submit their legal names. Nicknames and abbreviated names can cause verification failures, which require you to request more information. You can tweak your signup form to help avoid these errors though. Include a sentence like “Enter your legal name as it appears on your ID or SSN card.” and list the field names as:

  • Legal First Name
  • Legal Last Name

How we use SSN

For individuals in the U.S., Stripe is required to collect SSNs for tax purposes like filing 1099s. For businesses, SSNs help verify the company representative’s identity. If a company representative doesn’t want to provide their SSN, Stripe can verify their identity via a photo ID. This often requires more steps and takes longer to verify. If your users have questions regarding why Stripe needs this information, you can share this support article with them.

Submitting with the Stripe Dashboard

It’s recommended that you use the API to submit verification information, but you can use the Stripe Dashboard if needed. This includes uploading photo IDs. Once an account is verified, you can’t change business or company representative information. If you need to change this information after an account is verified, contact support to enable changes.

Verification status

Verification status can be unverified, pending, or verified. Pending is for occasions when Stripe can’t verify the information using proprietary algorithms and regulated third parties. If automatic verification fails (using the provided name, date of birth, personal ID number, etc.), then a photo ID is required. If the photo ID fails automatic verification too, Stripe manually reviews the submission. After review, Stripe either accepts the failure or manually verifies the account.

Unverified means Stripe is not able to verify the entity, either because verification failed or we don’t have enough information to attempt verification. This usually happens when verification information hasn’t been submitted yet, or information is missing. You can check the fields_needed attribute to see what’s missing, and have your connected account submit the required information.

Verified means all the required information passed verification checks. If you want to view the verification status for all of your connected accounts, you can use the list_accounts API call and inspect the account_object-verification and account_object-email attributes.

Incomplete verification

If verification fails, it triggers the account.updated event, which includes the information needed to complete the verification process. Your engineering team can build a flow that listens to this event, and automatically prompts users for the required information. We let you build this flow so you can use your branding, and decide how to contact your connected accounts (email, SMS, etc.). The Testing Custom Account Verification page has information on testing this process and fulfilling the different stages.

Updating verification information

To update a connected account’s verification information depends on whether the account was verified or not. If it was verified, you can contact our support team or have the connected account resubmit their verification information. If you contact customer support, you need to provide:

  • The connected account’s ID (e.g., acct_19AlIWDZGbDZjWrj)
  • The verification information that you need to update (e.g., legal_entity.first_name)

If you’re going to have your connected account resubmit their verification information using your form, let Stripe’s support team know that you need the account to be marked unverified. If the connected account wasn’t previously verified, you can use the API to resubmit the verification information using the update_account call.

Managing connected accounts after submission

There are several actions you can take after connected accounts submit their verification information. These actions are often taken when businesses are flagged for fradulent behavior, are created accidentally, or if they close.

Deactivating accounts

If you want to prevent an account from processing payments, but you don’t want to delete it, you can switch it to manual payouts. This doesn’t technically deactivate the account, but it prevents future payouts and charges. Stripe only charges for connected accounts that actively process payments, so you aren’t charged if you switch an account to manual payouts. If the business becomes active again, you can switch it back to automatic payouts.

Rejecting accounts

You can reject accounts using the Dashboard or the reject_account API. Rejecting accounts is permanent, so be certain the account is fraudulent. If you can’t reject an account because it has a negative balance, review the refund flow for negative balances. If you need to temporarily pause an account’s activities, switch it manual payouts and stop creating charges for it.

Fraudulent accounts

If the Stripe Risk team believes a connected account is fraudulent, they may reject the account and email you. If you have a webhook endpoint for the account.updated event, it’s triggered as well. To mitigate risk, Stripe doesn’t share why accounts are marked fraudulent, other than providing the disabled_reason. Stripe uses machine learning and manual reviews to identify fraudulent behavior, which gives us confidence in marking accounts as fraudulent.

For exceptional cases, you can write to Stripe support and request the decision be reviewed. Depending on the case, our Risk team may review the decision and provide more information. This process is labor intensive, and it’s recommended you only do this when you’re positive the connected account isn’t fraudulent, and you can take on the risk.

Sanctions concerns

As a U.S. company, Stripe complies with all sanctions programs administered by the U.S. Office of Foreign Assets Control (OFAC), along with a number of other national and international sanctions regimes. This includes both prohibitions against interactions with certain individuals and entities as well as comprehensive bans on business dealings involving certain countries or regions that are targeted by sanctions regimes.

Stripe screens all accounts, including connected accounts, in compliance with our own obligations under these sanctions regimes. If a connected account is flagged as a possible sanctions concern, Stripe will pause payouts from the connected account and reach out to the platform via email to request additional information. If there is a particular email address you would like sanctions-related requests to be sent to, please let your Stripe contact or our customer support team know. You can also set up webhooks to listen for sanctions-related events, which will appear as account.updated, disabled_reason: listed.

Payouts from the connected account will remain paused until the review has been cleared. Disregarding or violating sanctions can lead to fines, regulatory action, and loss of licensing for both Stripe and our users.

Was this page helpful? Yes No


Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

On this page