Handling verification with the API

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

Platforms with Custom accounts are required to provide Stripe with necessary information about their users for Know Your Customer (KYC) purposes. As a Connect platform with Custom accounts, it’s your responsibility to collect the required information from your users and provide it to Stripe. 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

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

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.
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.
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 (e.g., if the dob has already been verified, it doesn’t need to be provided again in subsequent updates).

After an individual is verified, you can’t change that individual’s information. For verified companies, you’ll need to contact support to make changes (e.g., the name or EIN on file).

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

Reason	Meaning
`action_required.requested_capabilities`	You need to request capabilities for the connected account. For details, see Request and unrequest capabilities.
`requirements.past_due`	Additional verification information is required to enable payout or charge capabilities on this account.
`requirements.pending_verification`	Stripe is currently verifying information on the connected account.
`rejected.fraud`	Account is rejected due to suspected fraud or illegal activity.
`rejected.terms_of_service`	Account is rejected due to suspected terms of service violations.
`rejected.listed`	Account is rejected because it's on a third-party prohibited persons or companies list (such as financial services provider or government).
`rejected.other`	Account is rejected for another reason.
`listed`	Account might be on a prohibited persons or companies list (Stripe will investigate and either reject or reinstate the account appropriately).
`under_review`	Account is under review by Stripe.
`other`	Account 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.",
          }
      ]
  }
{
  "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.",
          }
      ]
  }

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

Country: