Upcoming requirements updates

Last updated: October 13, 2025

Understand the changes to verification requirements

To align with regulations from the UK Financial Conduct Authority (FCA) and the Central Bank of Ireland (CBI), Stripe is updating our verification requirements for Know Your Customer (KYC) and ultimate beneficial owners (UBO) and directors.

If your connected accounts operate in any of the listed countries, you might need to update your onboarding flow. Failure to make required updates will disrupt your connected accounts’ access to payments and financial services.

To learn more about what is changing and why, see the new compliance requirements support article.

The upcoming changes affect connected accounts in the following countries:

Choose an integration approach

Stripe recommends using Stripe-hosted or Embedded onboarding to collect business and identity verification requirements. These options require fewer resources to implement and maintain than using API onboarding. The following table describes the major differences:

• Stripe-hosted onboarding: Recommended Send accounts to a Stripe-hosted flow to submit required information.
• Embedded onboarding: Recommended Embed Stripe-provided onboarding components that let accounts submit information directly to Stripe from within your app.
• API onboarding: Build and manage a custom onboarding flow using Stripe APIs.

Learn more about Connect onboarding options and migrating your API-based onboarding and remediation flows to Stripe-hosted or embedded flows.

The changes you make to your onboarding flow depend on how you collect onboarding information. In addition to updating your onboarding flow, update your internal and external documentation as needed, and prepare your support teams to answer questions about the updates.

If you use Stripe-hosted or Embedded onboarding, then you don’t need to update your integration to prepare for these requirement updates. However, you can communicate to your connected accounts that Stripe might request new or updated identity information when requirements change.

API integration overview

If you choose not to migrate to Stripe-hosted or Embedded onboarding, then you need to address the following updates:

• Know Your Customer (KYC) verification
• Ultimate beneficial owner (UBO) and director relationship verification
• Netherlands business registration (KvK) requirements
• New error codes

Update timeline

The following timeline explains the key milestones for these changes. Make sure to update and test your integration early to avoid any issues when the new requirements take effect.

Know your customer (KYC) verification

Stripe is strengthening our identity verification process, which might require some of your connected accounts to provide additional information. We’re also adding more options to the API for verifying information.

The following entities must provide verifiable KYC information:

• Legal entity (for individuals and sole proprietor entities);
• Account representative
• UBOs and directors (for accounts deemed high risk by the Stripe risk model)

Additional verification methods

You can improve verification success rates by using the following methods in addition to standard keyed-in information:

• National ID verification: Recommended Collect a national ID number up front to increase first-pass verification rates.
• Stripe Identity: Use selfie and document capture for accounts that fail automatic verification.
• Upload additional documents: Submit supporting identity or address documents for manual review.

Stripe Identity Recommended

You can attempt to verify connected accounts that fail their automatic verification by using Stripe Identity. Identity works by capturing a selfie and an ID document. Most European countries support Stripe Identity, and success rates vary by country.

Create an Identity verification session and use the related_person parameter to submit document and proof_of_liveness requirements for the person. You can check the results using the API or the Dashboard.

National ID verification Public preview

In the countries affected by this update, you can improve verification of a connected account representative by providing their national ID number in addition to their name, birthdate, address, and nationality.

Verification currently supports only the following national ID numbers.

You can provide national ID numbers only for connected accounts in the countries affected by this update. For example, you can provide the ID number for a Spanish citizen acting as a representative for a connected account in Austria, but you can’t provide the ID number for a Spanish citizen acting as a representative for a connected account in the US.

// Creating a connected account in Spain
> curl https://api.stripe.com/v1/accounts \
  -u sk_test_123 \
  -H "Stripe-Version: 2025-08-27.basil;experimental_onboarding_preview=v2" \
  -d 'type'='custom' \
  -d 'country'='ES' \
  -d 'capabilities[card_payments][requested]'='true' \
  -d 'capabilities[card_payments][preview]'='true' \
  -d 'capabilities[transfers][requested]'='true'

{
  "id": "acct_1Nv0FGQ9RKHgCVdB",
  ...
  "requirements": {
    "past_due": [
      ...
      "representative.nationality",
      ...
    ]
  }
 ...
}

> curl https://api.stripe.com/v1/accounts/acct_1Nv0FGQ9RKHgCVdB/persons \
  -u sk_test_123: \
  -d first_name=John \
  -d last_name=Doe

{
  "id": "person_1N9XNb2eZvKYlo2CjPX7xF6B",
  ...
}

> curl https://api.stripe.com/v1/accounts/acct_1Nv0FGQ9RKHgCVdB -u sk_test_123:

{
  ...
  "requirements": {
    "past_due": [
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.dob.year",
      ...other person requirements...
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.nationality"
    ]
  }
 ...
}

> curl https://api.stripe.com/v1/accounts/acct_1Nv0FGQ9RKHgCVdB/persons/person_1N9XNb2eZvKYlo2CjPX7xF6B \
  -u sk_test_123: \
  -d nationality=ES

> curl https://api.stripe.com/v1/accounts/acct_1Nv0FGQ9RKHgCVdB -u sk_test_123:

{
  "requirements": {
    "past_due": [
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.dob.year",
      ...other person fields...
    ],
    "alternatives": [
      {
        "original_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.dob.year",
          ...other person fields...
        ],
        "alternative_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.id_number"
        ]
      }
    ]
  }
}

> curl https://api.stripe.com/v1/accounts/acct_1Nv0FGQ9RKHgCVdB/persons/person_1N9XNb2eZvKYlo2CjPX7xF6B \
  -u sk_test_123: \
  -d 'id_number'='74362315-A' \
  ...other person fields...

> curl https://api.stripe.com/v1/accounts/acct_1Nv0FGQ9RKHgCVdB/ -u sk_test_123:

{
  "requirements": {
    "pending_verification": [
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.address.city",
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.address.line1",
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.address.postal_code",
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.dob.day",
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.dob.month",
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.dob.year",
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.first_name",
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.id_number",
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.last_name"
    ],
  }
}

> curl https://api.stripe.com/v1/accounts/acct_1Nv0FGQ9RKHgCVdB -u sk_test_123:

{
  "requirements": {
    // 1. They can check the information they've entered for dob, name, and address, and re-enter the correct information.
    "past_due": [
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.first_name",
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.last_name",
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.address.*",
    ],
    "alternatives": [
      // 2. They can check the information they entered for dob, name, address and id_number and re-key correct information.
      {
        "original_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.first_name",
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.last_name",
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.address.*",
        ],
        "alternative_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.id_number"
        ]
      },
      // 3. They can upload document that matches their name and address
      {
        "original_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.first_name",
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.last_name",
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.address.*"
        ],
        "alternative_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.verification.additional_document"
        ]
      },
      // 4. They can complete Stripe Identity
      {
        "original_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.first_name",
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.last_name",
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.address.*"
        ],
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.proof_of_liveness"
        ]
      },
    ]
  }
}

> curl https://api.stripe.com/v1/accounts/acct_1Nv0FGQ9RKHgCVdB -u sk_test_123:
{
  "requirements": {
    "past_due": [
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.name",
      "person_1N9XNb2eZvKYlo2CjPX7xF6B.address"
    ],
    "alternatives": [
      {
        "original_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.name",
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.address"
        ],
        "alternative_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.id_number"
        ]
      },
      {
        "original_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.name",
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.address"
        ],
        "alternative_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.proof_of_liveness"
        ]
      },
      {
        "original_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.name",
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.address"
        ],
        "alternative_fields_due": [
          "person_1N9XNb2eZvKYlo2CjPX7xF6B.verification.additional_document"
        ]
      }
    ]
    "errors": [
      {
        "code": "verification_failed_keyed_in_mismatch",
        "reason": "Identity information could not be verified."
        "requirement": "person_1N9XNb2eZvKYlo2CjPX7xF6B.name"
      },
      {
        "code": "verification_failed_keyed_in_mismatch",
        "reason": "Identity information could not be verified."
        "requirement": "person_1N9XNb2eZvKYlo2CjPX7xF6B.address"
      },
      {
        "code": "verification_failed_keyed_in_mismatch",
        "reason": "Identity information could not be verified."
        "requirement": "person_1N9XNb2eZvKYlo2CjPX7xF6B.id_number"
      }
    ]
  }
}

Relationship verification for UBOs and directors

Stripe is enhancing our verification process for ultimate beneficial owners (UBOs) and directors. European regulations require verification of the relationship of UBOs and directors to the legal entity:

• UBO: An individual who owns or controls (directly or indirectly) more than 25% of a legal entity (for example, companies, corporations, LLCs, and partnerships).
• Director: A board member or senior person responsible for managing a business (for example, CEO, COO, managing director).

The following table shows the relationships that must be verified for each legal entity type:

Verify UBO and director information

Connected accounts type in UBO or director information (name, date of birth, address). Stripe attempts to verify the person’s relationship to the legal entity using third-party sources. If automatic verification fails, the account must provide additional documentation.

The additional documentation can be either an official document upload or a digital attestation:

• Official document upload: The account uploads an official document that confirms the relationship.
• Digital attestation: An authorized person signs and uploads a document attesting to the ownership or director relationship.

If the account chooses digital attestation, use the following document templates:

• Ultimate beneficial owner digital attestation template
• Director digital attestation template

{
  "requirements": {
    "past_due": ["documents.proof_of_ultimate_beneficial_ownership.files"],
    "errors": [{
      "requirement": "documents.proof_of_ultimate_beneficial_ownership.files",
      "code": "invalid_signator",
      "reason": "Unauthorized attestation signer. The signer must have a documented relationship with the legal entity."
    }]
  }
}

{
  "requirements": {
    "past_due": ["documents.proof_of_ultimate_beneficial_ownership.files"],
    "errors": [{
      "requirement": "documents.proof_of_ultimate_beneficial_ownership.files",
      "code": "verification_document_name_mismatch",
      "reason": "The attestation document is no longer valid due to changes in beneficial ownership information. Upload a new attestation reflecting the current ownership structure."
    }]
  }
}

{
  "requirements": {
    "past_due": ["documents.proof_of_registration.files"],
    "errors": [{
      "requirement": "documents.proof_of_registration.files",
      "code": "verification_document_failed_other",
      "reason": "Your team can contact Stripe to learn more about why identity verification failed."
    }]
  }
}

{
  "error": {
    "code": "invalid_signator",
    "message": "signer.person can only be provided when a file is also provided",
    "type": "invalid_request_error"
  }
}

Prefill UBO and director information Private preview

Optionally, you can also integrate with an API that programmatically detects and prefills UBOs or directors associated with a legal entity. The connected account can verify the relationship by confirming the detected information instead of through document upload or digital attestation.

This path can increase verification rates and reduce friction, but it doesn’t work for all accounts. You still need to handle document uploads or digital attestations for accounts where Stripe can’t prefill their relationships.

If you’re interested in prefill for UBO or director verification, sign up to express your interest below.

Netherlands business registration (KvK) requirements

Starting in 2026, we’re enforcing stricter business type requirements for Netherlands (NL) accounts to ensure compliance with Dutch regulations. This specifically affects how we collect the KvK (Kamer van Koophandel), the unique 8-digit company registration number required for businesses in the Netherlands.

What’s changing

1. Individual business type is no longer supported

The individual business type is no longer supported for Netherlands accounts. This affects: Existing and new NL accounts with business_type: "individual" and business_type: "sole_proprietorship"

Why this matters: In the Netherlands, every business must provide a KvK (Chamber of Commerce) number. Our “individual” business type doesn’t collect a KvK, which makes it non-compliant.

2. New error code: unsupported_business_type

Accounts with invalid business types see a new error in their requirements:

// Account with unsupported business type
{
  "id": "acct_123",
  "business_type": "individual",
  "country": "NL",
  "requirements": {
    "past_due": ["business_type"],
    "errors": [{
      "requirement": "business_type",
      "code": "unsupported_business_type",
      "reason": "Business type isn't supported in merchant country. 'individual' isn't a supported business type in country NL."
    }]
  }
}

3. Collect KvK registration for unincorporated accounts

Existing and new NL accounts with the following business types and structures are required to provide KvK registration.

• business_type: "company" and business_structure: "unincorporated_partnership"
• business_type: "non_profit" and business_structure: "unincorporated_non_profit"

Why this matters: unincorporated accounts are currently not required to provide a KvK number, which violates Dutch compliance requirements. All NL businesses must provide their KvK registration.

How to resolve

For existing accounts

Existing NL accounts with individual business type must update to company with sole_proprietorship structure to stay compliant when we start rolling out this new requirement:

// Update existing account
curl -X POST https://api.stripe.com/v1/accounts/acct_123 \
  -u sk_test_123: \
  -d "business_type=company" \
  -d "company[structure]=sole_proprietorship" \
  -d "company[tax_id]=12345678"  // KvK number

// Successful response
{
  "id": "acct_123",
  "business_type": "company",
  "company": {
    "structure": "sole_proprietorship",
    "tax_id": "12345678"
  },
  "requirements": {
    "past_due": [],  // business_type requirement resolved
    "errors": []
  }
}

For new account creation

Attempting to create a Netherlands account with an individual business type will return the unsupported_business_type error.

// This will fail
curl -X POST https://api.stripe.com/v1/accounts \
  -u sk_test_123: \
  -d "country=NL" \
  -d "type=custom" \
  -d "business_type=individual"

// Response
{
  "id": "acct_123",
  "business_type": "individual",
  "country": "NL",
  "requirements": {
    "past_due": ["business_type"],
    "errors": [{
      "requirement": "business_type",
      "code": "unsupported_business_type",
      "reason": "Business type isn't supported in merchant country. 'individual' isn't a supported business type in country NL."
    }]
  }


// Correct approach
curl -X POST https://api.stripe.com/v1/accounts \
  -u sk_test_123: \
  -d "country=NL" \
  -d "type=custom" \
  -d "business_type=company" \
  -d "company[structure]=sole_proprietorship"

Supported business structures for NL

For Netherlands accounts, use these business type and structure combinations:

Impact on capabilities

Accounts with unsupported_business_type error will have their capabilities restricted until the business type is updated:

{
  "capabilities": {
    "card_payments": "inactive",
    "transfers": "inactive"
  },
  "requirements": {
    "disabled_reason": "requirements.past_due",
    "past_due": ["business_type"]
  }
}

Accounts have not provided their KvK registration will have their card_payments capability restricted until this information is provided:

{
  "capabilities": {
    "card_payments": "inactive"
  },
  "requirements": {
    "disabled_reason": "requirements.past_due",
    "past_due": ["company.tax_id"]
  }
}

Migration timeline

• Now: New error code unsupported_business_type is active
• When Future requirements rollout: Existing accounts must start remediation
• September 30, 2026: All NL accounts must be compliant

Implementation Checklist

For platforms with NL connected accounts:

1. Audit existing accounts

// Find affected accounts
const accounts = await stripe.accounts.list({
  limit: 100,
  // Filter for NL accounts in your system
});

const affected = accounts.data.filter(a =>
  a.country === 'NL' &&
  a.business_type === 'individual'
);

1. Update account creation flows

   • Remove individual option for NL accounts
   • Default to company with sole_proprietorship
   • Collect KvK number (company.tax_id)

2. Handle the new error code

if (account.requirements.errors.some(e =>
  e.code === 'unsupported_business_type')) {
  // Prompt user to update business type
  // Guide them to select appropriate structure
  // Collect KvK number
}

1. Communicate with affected connected accounts

   • Explain why the change is needed
   • Provide guidance on selecting correct business structure
   • Help them locate their KvK number

Testing

Test your implementation with these scenarios:

// Test updating to valid business type
const updated = await stripe.accounts.update('acct_test_123', {
  business_type: 'company',
  company: {
    structure: 'sole_proprietorship',
    tax_id: '12345678'  // Test KvK
  }
});

Additional considerations

Individual freelancers

In the Netherlands, even individual freelancers must register as a business (eenmanszaak) and obtain a KvK number. They should select company → sole_proprietorship.

How to find the KvK number for connected accounts

The KvK number is on their Chamber of Commerce registration certificate (uittreksel Kamer van Koophandel).

Backward compatibility

In older API versions, unsupported_business_type appears as invalid_value_other with a detailed_code field containing the specific error.

New error codes

verification_data_not_found

The new error code verification_data_not_found can appear in the requirements.errors array on the Account object. This error signals that Stripe was unable to retrieve information (such as UBO or Director/Officer data) from third-party verification providers using the connected account’s known legal entity details. That can happen for a number of reasons, but it’s often because the account entered their information incorrectly.

This “data not found” error is distinct from existing verification error codes:

• verification_missing_owners: Indicates that known owners are missing from the account.
• verification_failed_keyed_match: Indicates a mismatch between submitted information and verification sources.

// Example: verification_data_not_found error
{
  "requirements": {
    "errors": [{
      "requirement": "owners",
      "code": "verification_data_not_found",
      "reason": "Stripe was unable to retrieve ownership or director information from third-party providers based on the current legal entity details. Verify that the business information on the account is correct."
    }]
  }
}

To handle this error, prompt the connected account to review and correct their legal entity information (company name, registration number, address). If they update their information, Stripe automatically attempts to verify it again.

If the account information is correct, or if Stripe still can’t verify updated information, use a manual verification method such as document upload or digital attestation.

Testing

You can create test accounts to use when developing and testing your integration. Test accounts can simulate different verification outcomes, allowing you to see how the API returns requirements and errors for each case.

The following examples help you prepare for the upcoming EU requirements changes. For more information about Connect testing in general, see Testing Stripe Connect.

Create a test account

Create a test Account by sending a POST request to the Accounts API using your sandbox secret key.

To access the new requirements before they are released to non-test mode accounts, set a header enabling a preview version of the API, enable the experimental onboarding preview feature, and enable the preview version when requesting a capability. For example:

curl https://api.stripe.com/v1/accounts \
  -u sk_test_123: \
  -H "Stripe-Version: 2026-01-28.preview;experimental_onboarding_preview=v2" \
  -d 'type'='custom' \
  -d 'country'='ES' \
  -d 'capabilities[card_payments][requested]'='true' \
  -d 'capabilities[card_payments][preview]'='true' \
  -d 'capabilities[transfers][requested]'='true'

The examples below demonstrate how to simulate different situations by using values that trigger specific responses for test accounts.

Test an Account belonging to an individual

This example creates an account that doesn’t require relationship verification because the business entity type is individual.

Create a test account following the earlier instructions, then set the basic business details:

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123: \
  -d business_type=individual \
  -d "business_profile[mcc]"=5995 \
  -d "business_profile[url]"="https://accessible.stripe.com"

The response includes the basic requirements for an individual. You can meet these requirements by creating a representative:

curl https://api.stripe.com/v1/accounts/acct_test_123/persons \
  -u sk_test_123: \
  -d "first_name=Marie" \
  -d "last_name=Dupont" \
  -d "dob[year]=1901" \
  -d "dob[month]=1" \
  -d "dob[day]=1" \
  -d "address[line1]=address_full_match" \
  -d "address[city]=Madrid" \
  -d "address[postal_code]=28009" \
  -d "address[country]=ES" \
  -d "email=test@example.com" \
  -d "phone=%2B35366666666" \
  -d "nationality=ES" \
  -d "relationship[representative]=true"

Specifying the DOB 1901-01-01 triggers successful identity verification in test mode. For other result triggers, see Test dates of birth. Similarly, setting the first line of the address to the string address_full_match triggers successful verification of the address. For other result triggers, see Test business addresses.

The response shows that the individual’s requirements have become pending. If you wait a few moments and retrieve the Account, you can see that those requirements have been cleared:

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123

The only remaining requirements are for the bank account (external_account) and terms of service (TOS). To clear the terms of service requirements, set the Account’s tos_acceptance hash:

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123: \
  -d "tos_acceptance[date]=1540248693" \
  -d "tos_acceptance[ip]=10.0.0.1"

To clear the bank account requirements, create a test bank account for the Account. Specify a test bank account number according to its country:

curl https://api.stripe.com/v1/accounts/acct_test_123/external_accounts \
  -u sk_test_123: \
  -d "external_account[object]=bank_account" \
  -d "external_account[account_number]=ES0700120345030000067890" \
  -d "external_account[country]=ES" \
  -d "external_account[currency]=EUR"

Test an Account belonging to a company

This example creates an account that is subject to relationship verification requirements because the business entity type is company.

Create a test account following the earlier instructions, then set the basic business details:

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123: \
  -d business_type=company \
  -d "business_profile[mcc]"=5995 \
  -d "business_profile[url]"="https://accessible.stripe.com" \
  -d "company[name]=Test company" \
  -d "company[phone]=628123456787" \
  -d "company[address][line1]=address_full_match" \
  -d "company[address][city]=Madrid" \
  -d "company[address][postal_code]=28009" \
  -d "company[address][country]=ES" \
  -d "company[tax_id]=000000000"

Specifying the tax ID number 000000000 triggers successful verification of the company. For other result triggers, see Test business tax IDs.

Next, provide a representative.

curl https://api.stripe.com/v1/accounts/acct_test_123/persons \
  -u sk_test_123: \
  -d "first_name=Adam" \
  -d "last_name=" \
  -d "dob[year]=1901" \
  -d "dob[month]=1" \
  -d "dob[day]=1" \
  -d "address[line1]=address_full_match" \
  -d "address[city]=Madrid" \
  -d "address[postal_code]=28009" \
  -d "address[country]=ES" \
  -d "email=test@example.com" \
  -d "phone=%2B35366666666" \
  -d "nationality=ES" \
  -d "relationship[representative]=true" \
  -d "relationship[title]=CEO"

After the verification process for the representative completes, you can see the remaining requirements with a GET request:

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123:

The requirements in the requirements.currently_due array list the details we need about the owners on the Account. The requirements.alternatives array can include optional information that you can provide to fulfill certain requirements. For example:

{
  "alternative_fields_due": [
    "company.owners_provided",
    "documents.proof_of_ultimate_beneficial_ownership.files",
    "owners.first_name",
    "owners.last_name"
  ],
  "original_fields_due": [
    "company.owners_provided",
    "owners.first_name",
    "owners.last_name"
  ]
}

You can provide the fields listed in alternative_fields_due as another way to fulfill the requirements in the corresponding original_fields_due list. In this example, alternative_fields_due includes the properties in original_fields_due, plus documents.proof_of_ultimate_beneficial_ownership.files. That means the original information is required, but you have the option to also provide a document proving ultimate beneficial ownership to help the verification process.

To meet the owner requirements, create two persons and mark them as owners. The names in this example are hard-coded values for test accounts that use the tax ID number 000000000.

curl https://api.stripe.com/v1/accounts/acct_test_123/persons \
  -u sk_test_123: \
  -d "first_name=Marie" \
  -d "last_name=Dupont" \
  -d "dob[year]=1901" \
  -d "dob[month]=1" \
  -d "dob[day]=1" \
  -d "address[line1]=address_full_match" \
  -d "address[city]=Madrid" \
  -d "address[postal_code]=28009" \
  -d "address[country]=ES" \
  -d "email=owner@example.com" \
  -d "relationship[owner]=true"

curl https://api.stripe.com/v1/accounts/acct_test_123/persons \
  -u sk_test_123: \
  -d "first_name=Louis" \
  -d "last_name=Martin" \
  -d "dob[year]=1901" \
  -d "dob[month]=1" \
  -d "dob[day]=1" \
  -d "address[line1]=address_full_match" \
  -d "address[city]=Madrid" \
  -d "address[postal_code]=28009" \
  -d "address[country]=ES" \
  -d "email=owner@example.com" \
  -d "relationship[owner]=true"

Indicate that you’ve created all of the Account’s owners by setting company.owners_provided to true:

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123: \
  -d "company[owners_provided]=true"

Completing this request removes all the owner requirements from the Account.

Test fallback to document verification

An Account’s owner requirements remain in currently_due (or in pending_verification, if verification is in progress) until verification is successful.

When verification fails, one of your options is to upload a document. This example shows how to do so using the API.

Create a test account following the earlier instructions, then set the basic business details. Set the tax ID number to 222221001, which triggers owner verification failure.

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123: \
  -d business_type=company \
  -d "business_profile[mcc]"=5995 \
  -d "business_profile[url]"="https://accessible.stripe.com" \
  -d "company[name]=Test company" \
  -d "company[phone]=628123456787" \
  -d "company[address][line1]=address_full_match" \
  -d "company[address][city]=Madrid" \
  -d "company[address][postal_code]=28009" \
  -d "company[address][country]=ES" \
  -d "company[tax_id]=222221001"

Next, provide a representative:

curl https://api.stripe.com/v1/accounts/acct_test_123/persons \
  -u sk_test_123: \
  -d "first_name=Marie" \
  -d "last_name=Dupont" \
  -d "dob[year]=1901" \
  -d "dob[month]=1" \
  -d "dob[day]=1" \
  -d "address[line1]=address_full_match" \
  -d "address[city]=Madrid" \
  -d "address[postal_code]=28009" \
  -d "address[country]=ES" \
  -d "email=test@example.com" \
  -d "phone=%2B35366666666" \
  -d "nationality=ES" \
  -d "relationship[representative]=true" \
  -d "relationship[title]=CEO"

Then, create an owner:

curl https://api.stripe.com/v1/accounts/acct_test_123/persons \
  -u sk_test_123: \
  -d "first_name=Adam" \
  -d "last_name=Smith" \
  -d "dob[year]=1901" \
  -d "dob[month]=1" \
  -d "dob[day]=1" \
  -d "address[line1]=address_full_match" \
  -d "address[city]=Madrid" \
  -d "address[postal_code]=28009" \
  -d "address[country]=ES" \
  -d "email=owner@example.com" \
  -d "relationship[owner]=true"

Indicate that you’re done creating owners by setting company.owners_provided to true:

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123: \
  -d "company[owners_provided]=true"

If you examine the Account, you can see that the owner requirements remain and the requirements.errors array contains an entry with a requirement of owners and a code of verification_data_not_found. That means Stripe wasn’t able to verify the owners using the provided company information.

If you receive this error for a real Account, check that you entered the details for the correct legal entity. This example assumes that the details are correct, and that you need to provide a document to verify them.

For a real Account, use the Files API to upload a document, then update the Account using the token returned in the response. For this example, use the test token file_relationship_document_success.

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123: \
  -d "documents[proof_of_ultimate_beneficial_ownership][files][]"=file_relationship_document_success

A few moments after updating the Account, you can get the current requirements and see that the owner requirements have been cleared.

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123:

Test a company with no applicable owners

If a company has no owners with more than 25% ownership, Stripe requires the director information instead. This example demonstrates how to provide director information.

Create a test account following the earlier instructions, then set the basic business details. Set the tax ID number to 000000000, which triggers company verification success.

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123: \
  -d business_type=company \
  -d "business_profile[mcc]"=5995 \
  -d "business_profile[url]"="https://accessible.stripe.com" \
  -d "company[name]=Test company" \
  -d "company[phone]=628123456787" \
  -d "company[address][line1]=address_full_match" \
  -d "company[address][city]=Madrid" \
  -d "company[address][postal_code]=28009" \
  -d "company[address][country]=ES" \
  -d "company[tax_id]=000000000"

Next, provide a representative:

curl https://api.stripe.com/v1/accounts/acct_test_123/persons \
  -u sk_test_123: \
  -d "first_name=Marie" \
  -d "last_name=Dupont" \
  -d "dob[year]=1901" \
  -d "dob[month]=1" \
  -d "dob[day]=1" \
  -d "address[line1]=address_full_match" \
  -d "address[city]=Madrid" \
  -d "address[postal_code]=28009" \
  -d "address[country]=ES" \
  -d "email=test@example.com" \
  -d "phone=%2B35366666666" \
  -d "nationality=ES" \
  -d "relationship[representative]=true" \
  -d "relationship[title]=CEO"

To indicate that the business has no relevant owners, set company.owners_provided to true without creating any owners. To reuse an existing test Account that has owners, you can remove all the existing owners.

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123: \
  -d "company[owners_provided]=true"

The requirements.alternatives array contains a set of director properties as an alternative to the owner properties. The process for creating a director is very similar to the process for creating an owner:

curl https://api.stripe.com/v1/accounts/acct_test_123/persons \
  -u sk_test_123: \
  -d "first_name=Adam" \
  -d "last_name=Smith" \
  -d "dob[year]=1901" \
  -d "dob[month]=1" \
  -d "dob[day]=1" \
  -d "address[line1]=address_full_match" \
  -d "address[city]=Madrid" \
  -d "address[postal_code]=28009" \
  -d "address[country]=ES" \
  -d "email=owner@example.com" \
  -d "relationship[director]=true" \
  -d "relationship[title]=President"

Indicate that you’re done creating directors by setting company.directors_provided to true:

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123: \
  -d "company[directors_provided]=true"

To simulate a successful relationship verification, set company.name to the string match_name_relationships:

curl https://api.stripe.com/v1/accounts/acct_test_123 \
  -u sk_test_123: \
  -d "company[name]=match_name_relationships"

Other test cases

The following tests are also valuable:

• A non_profit type entity, which requires director verification (UBO verification isn’t an option).
• Meeting director verification requirements using a document.
• Companies in the UK that require both UBO verification and director verification.