API onboarding

Build your own onboarding flow using Stripe's APIs.

With API onboarding, you use the Accounts API to build an onboarding flow, reporting functionality, and communication channels for your users. Stripe can be completely invisible to the account holder. However, your platform is responsible for all interactions with your accounts and for collecting all the information needed to verify them.

Additional responsibilities

With API onboarding, your custom flow must meet all legal and regulatory requirements in the regions where you do business. You must also commit resources to track changes to those requirements and collect updated information on an ongoing basis, at least once every six months. If you want to implement a customized onboarding flow, Stripe strongly recommends that you use embedded onboarding.

Establish requirements

The following factors affect the onboarding requirements for your connected accounts:

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)

Use the interactive form to see how changing these factors affects the requirements.

Requirements form

Inspect all the requirements necessary for your selected combinations. Pay particular attention to the Requirement column. That column lists specific parameters on the account that you must collect to onboard it with the capabilities requested. Some parameters are only required at certain thresholds, as noted in the Required Before column.

Loading required verification information

Processing live charges and receiving payouts

In the UAE, company documents such as the Trade License and Proof of Bank Account as well as relevant identity documents must be verified before a connected account can start processing live charges and receiving payouts. For all businesses except sole establishments and free zone establishments, the Memorandum of Association must be verified as well.

Uploading identity documents

For the company representative, beneficial owners and executives, we require the following identity documents for verification:

Passport: all individuals
Emirates ID: UAE nationals & UAE residents
Residence visa: foreign nationals who are resident in the UAE

The Emirates ID can be provided in the parameter called verification.document. Passports and residence visas should be provided under a separate parameter called documents.

Keeping up to date with expired verification documents

In the UAE, Stripe is required to keep up to date with a company’s Trade License in addition to the primary identity document of the company’s representative, beneficial owners and executives. The primary identity document is either the Emirates ID for UAE nationals and residents, otherwise it is an individual’s Passport. Companies will have up to 28 days after the expiry date of these documents to provide an updated version. Expired documents will appear under company requirements or individual requirements and marked as currently due for two weeks before capabilities become disabled.

Ultimate Beneficial Owners

Stripe is required to verify all the beneficial owners of a business. These are the individuals who own 25% or more of the primary business. If a holding company has 25% or more ownership of the business, then the Memorandum of Association of this holding company as well that of the primary business must be uploaded. These documents must show the persons where relationship.owner is set to true.

Additional information on the company representative

This connected account needs to be activated by a person, known as the company representative, with significant responsibility to control, manage, or direct the organization and is authorized by the organization to agree to Stripe’s terms. The representative must either be an owner or an executive, which you specify by setting relationship.owner to true or relationship.executive to true. For a sole establishment or free zone establishment, the account must be activated by the owner of the business.

VAT Information

Stripe doesn’t charge UAE VAT on Stripe fees to customers located in the UAE, where a valid UAE VAT ID has been provided. Local UAE VAT self-assessment obligations may be triggered upon receipt of a monthly invoice from Stripe. Stripe does charge UAE VAT at 5% on Stripe fees to customers located in the UAE, where a valid UAE VAT ID hasn’t been provided.

Power of Attorney

If the company representative doesn’t appear on the company’s Trade License or the Memorandum of Association, then you must upload a Power of Attorney that shows that the company representative has the authority to act on behalf of the company or a notarized letter of authorization.

Supported business structures

In the UAE, the only possible business type is company and the following business structures are accepted:

sole_establishment
free_zone_establishment
llc
free_zone_llc

Additional information on the representative

If Stripe is unable to verify the representative, you need to provide a scan of an ID document. This can be collected with the verification.document.front and verification.document.back arguments.

Additional information on the owner

If Stripe is unable to verify the owner, you need to provide a scan of an ID document. This can be collected with the verification.document.front and verification.document.back arguments.

Additional information on the individual

If Stripe is unable to verify the individual, you need to provide a scan of an ID document. This can be collected with the individual.verification.document.front and individual.verification.document.back arguments.

Additional information on bank accounts

We’ll verify that the legal owner of each payout bank account matches that of the Stripe account.

If Stripe can’t verify the owner of the bank account, we’ll transition the status of the ExternalAccount to verification_failed. You’ll need to collect a scan of a cancelled check or bank statement to prove the legal owner of the bank account. Collect this information with the documents.bank_account_ownership_verification.files argument.

Provide ID document for the representative

You must provide a scan of an ID document for the representative. To collect this scan, use the verification.document.front and verification.document.back arguments.

Identity verification documents must be issued in Japan and show the representative’s residency status.

Provide ID document for the individual

You must collect a scan of an ID document for an individual. To collect this scan, use the individual.verification.document.front and individual.verification.document.back arguments.

Identity verification documents must be issued in Japan and show the individual’s residency status.

Special considerations

Collecting information for Japanese accounts is unique in that both kana and kanji language variations are required for a number of parameters:

first_name_kana
first_name_kanji
last_name_kana
last_name_kanji
name_kana
name_kanji
address_kana
address_kanji

You need to submit information for these parameters instead of their counterparts (that is, instead of first_name, last_name, and so forth). It might seem counterintuitive to provide two arguments that represent the same onboarding requirement, but Stripe can’t verify a Japanese account until we’ve received information for both language variations. These variations may be composed of full- or half-width hiragana, katakana, or Latin characters, with kanji-specific API parameters also allowing for kanji characters.

Japanese addresses

Both kana and kanji language variations apply to Japanese address requirements as well.

postal_code is always required when providing a Japanese address of either language variation. Stripe validates submitted addresses, and for a valid postal_code, we attempt to automatically fill attributes for matching state, city, and town for both address_kana and address_kanji.

Requests with address details that are incompatible with the provided postal_code fail.

line2 should contain the building name in addition to the room number if applicable. This attribute can be omitted when the address doesn’t contain building details.

Here’s an example representation of a Japanese address, with explanations for how each part maps to its corresponding Stripe API attribute:

// 〒150-0001 東京都渋谷区神宮前1-5-8 神宮前タワービルディング22F
{
  "country": "JP",
  "legal_entity": {
    "address_kana": {
      "country": "JP", // 2-letter country code
      "postal_code": "1500001", // Zip/Postal Code
      "state": "ﾄｳｷﾖｳﾄ", // Prefecture
      "city": "ｼﾌﾞﾔ", // City/Ward
      "town": "ｼﾞﾝｸﾞｳﾏｴ 1-", // Town/cho-me
      "line1": "5-8", // Block/Building number
      "line2": "ｼﾞﾝｸﾞｳﾏｴﾀﾜｰﾋﾞﾙﾃﾞｨﾝｸﾞ22F", // Building details (optional)
    },
    "address_kanji": {
      "country": "JP", // 2-letter country code
      "postal_code": "１５００００１", // Zip/Postal Code
      "state": "東京都", // Prefecture
      "city": "渋谷区", // City/Ward
      "town": "神宮前　１丁目", // Town/cho-me (no kanji numerals)
      "line1": "５－８", // Block/Building number
      "line2": "神宮前タワービルディング22F", // Building details (optional)
    }
  }
}

Statement descriptors

Statement descriptors explain charges or payments and include information that banks and card networks require to help customers understand their statements.

We recommend setting the static components of statement descriptors in all three supported scripts (kanji, kana, and Latin characters) for Japanese connected accounts.

	PARAMETER
Statement descriptor	settings.payments.statement_descriptor
Statement descriptor (kanji)	settings.payments.statement_descriptor_kanji
Statement descriptor (kana)	settings.payments.statement_descriptor_kana
Statement descriptor prefix	settings.card_payments.statement_descriptor_prefix
Statement descriptor prefix (kanji)	settings.card_payments.statement_descriptor_prefix_kanji
Statement descriptor prefix (kana)	settings.card_payments.statement_descriptor_prefix_kana

You can set these fields with API.

See Japanese statement descriptors for more details.

Additional information on the account

If Stripe is unable to verify the business entity, the entity doesn’t have a company.tax_id, or there are possible concerns about sanctions, you need to collect a proof of entity document to enable payouts. Collect it using the company.verification.document.front and company.verification.document.back arguments.

Companies with the card_payments capability

company refers to these types of entities:

Sociedad Anónima (S.A.)
Sociedad de Responsabilidad Limitada (S. de R.L.)
Sociedad Anónima Promotora de Inversión (S.A.P.I.)
Sociedad por Acciones Simplificada (S.A.S.)

Additional information on the individual

If the individual fails verification, doesn’t have an individual.id_number, or there are possible concerns about sanctions, then an ID document scan is required to enable payouts. You can collect that information using the individual.verification.document.front and individual.verification.document.back arguments.

Additional information on the representative

A person known as a representative must activate this connected account. The representative must be an authorized signatory with legal powers to represent the company as set forth under the relevant corporate documents, and must be authorized to agree to Stripe’s terms.

If Stripe is unable to verify the representative, the representative doesn’t have a representative.id_number, or there are possible concerns about sanctions, you must collect a scan of an ID document to enable payouts. Collect ID information using the verification.document.front and verification.document.back arguments.

Additional information on owners

You must collect information on all owners with more than 25% ownership of the company. When you have finished collecting the required owner information, you must inform Stripe by setting company.owners_provided to true.

If Stripe is unable to verify an owner, an owner doesn’t have an owners.id_number, or there are possible concerns about sanctions, you must collect a scan of an ID document to enable payouts. Collect ID information using the verification.document.front and verification.document.back arguments.

Optionally, you can collect ownership information on each person using the relationship.owner and relationship.percent_ownership arguments.

Additional information on the account

If Stripe is unable to verify the company, or if there are possible concerns about sanctions, you must collect a proof-of-entity document to enable payouts. Collect it using the company.verification.document.front and company.verification.document.back arguments.

Additional information on the individual

Depending on the situation, you might need to collect a scan of an ID document, an address document, or both to enable payouts. That can happen if Stripe is unable to verify the individual or if there are possible concerns about sanctions. Collect ID information using the individual.verification.document.front and individual.verification.document.back arguments.

Additional information on the representative

A person known as a representative must activate this connected account. The representative must be a beneficial owner who is authorized to sign for the company. Indicate that relationship to Stripe by setting relationship.executive to true, or, if the representative owns 25% or more of the company, by setting relationship.owner to true.

Depending on the situation, you might need to collect a scan of an ID document to enable payouts. That can happen if Stripe is unable to verify the representative or if there are possible concerns about sanctions. Collect ID information using the verification.document.front and verification.document.back arguments.

Optionally, you can collect the representative’s ownership information using the relationship.representative and relationship.percent_ownership arguments.

Additional information on directors

For companies (excluding partnerships), you must collect information on all directors. Directors are members of the governing board of the company. When you have finished collecting the required information from all directors, or if your company doesn’t have any directors, you must notify Stripe by setting company.directors_provided to true.

If there are possible concerns about sanctions, you must collect a scan of an ID document to enable payouts. Collect ID information using the verification.document.front and verification.document.back arguments.

Additional information on beneficial owners (for both executives and owners)

You must collect information on all beneficial owners. Beneficial owners are persons who exercise significant management control over the company (executives) or who own 25% or more of the company (owners). When you have finished collecting the required information from all beneficial owners, you must notify Stripe by setting both company.owners_provided and company.executives_provided to true.

Depending on the situation, you might need to collect a scan of an ID document to enable payouts. That can happen if Stripe is unable to verify a beneficial owner or if there are possible concerns about sanctions. Collect ID information using the verification.document.front and verification.document.back arguments.

Optionally, you can collect ownership information on each person who owns 25% or more of the company using the relationship.owner and relationship.percent_ownership arguments.

Additional information on the account

If Stripe can’t verify the company, or if there are possible concerns about sanctions, you must collect a proof-of-entity document to enable payouts. Collect it using:

Additional information on the individual

Depending on the situation, you might need to collect a scan of an ID document to enable payouts. That can happen if Stripe can’t verify the individual or if there are possible concerns about sanctions.

Collect ID information using:

Additional information on the representative

A person known as a representative must activate this connected account. This person must be a beneficial owner who is authorized to sign for the company. Indicate this relationship to Stripe by setting relationship.executive to true, or, if the representative owns 25% or more of the company, by setting relationship.owner to true.

Depending on the situation, you might need to collect a scan of an ID document to enable payouts. That can happen if Stripe can’t verify the representative or if there are possible concerns about sanctions. Collect ID information using the verification.document.front and verification.document.back parameters.

Optionally, you can collect the representative’s ownership information using relationship.representative and relationship.percent_ownership.

Additional information on directors

For companies (excluding partnerships), you must collect information on all directors. Directors are members of the governing board of the company. When you have finished collecting the required information from all directors, or if your company doesn’t have any directors, you must inform Stripe by setting company.directors_provided to true.

Additional information on beneficial owners (for both executives and owners)

You must collect information on all beneficial owners. Beneficial owners are persons who exercise significant management control over the company (executives) or who own 25% or more of the company (owners). When you have finished collecting the required information from all beneficial owners, you must inform Stripe by setting both company.owners_provided and company.executives_provided to true.

Depending on the situation, you might need to collect a scan of an ID document to enable payouts. That can happen if Stripe can’t verify a beneficial owner or if there are possible concerns about sanctions. Collect ID information using the verification.document.front and verification.document.back parameters.

Optionally, you can collect ownership information on each person who owns 25% or more of the company using relationship.owner and relationship.percent_ownership.

Additional information on the account

If Stripe can’t verify the company, or if there are possible concerns about sanctions, you must collect a proof-of-entity document to enable payouts. Collect it using the company.verification.document.front and company.verification.document.back arguments.

Additional information on the representative

If Stripe can’t verify the representative, they need to provide proof of liveness, which entails taking a selfie and uploading an ID document using Stripe Identity. Your platform needs to integrate with Connect Onboarding to satisfy this requirement.

Alternatively, you can provide a scan of an ID document and a scan of an address document. To collect an ID document, use the verification.document.front and verification.document.back parameters. To collect an address document, use the verification.additional_document.front and verification.additional_document.back parameters. You can’t provide the same document for both identity and address verification.

Additional information on the individual

Individuals that Stripe can’t verify must provide proof of liveness, which entails taking a selfie and uploading an ID document using Stripe Identity. Your platform needs to integrate with Connect Onboarding to allow such individuals to complete this requirement.

Alternatively, your platform can collect scans of an individual’s ID and address documents and upload them to Stripe. After uploading, submit the individual’s ID document with the individual.verification.document.front and individual.verification.document.back fields and the address document with the individual.verification.additional_document.front and individual.verification.additional_document.back fields. You can’t provide the same document for both identity and address verification.

Additional information on owners

You must collect information on all owners. Owners are any individual who owns 25% or more of the company. When you finish collecting the required information from all owners, set company.owners_provided to true. This lets Stripe know that you have completed this requirement.

Optionally, you can collect ownership information on each person who owns 25% or more of the company with relationship.owner and relationship.percent_ownership.

Additional information on directors

You must collect information on all directors. We check the director information you supply against the registry and results in one of these outcomes:

The business is found in the registry, and the information matches. The account fully onboards, and requires no additional action.
The business is found in the registry, but the director information doesn’t match. You must upload a proof of registration document using the documents.proof_of_registration.files parameter. Set the File’s purpose parameter to account_requirement.

This request uploads the file and returns a token:

{
  "id": "file_5dtoJkOhAxrMWb",
  "created": 1403047735,
  "size": 4908
}

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

Additional information on registration statuses

If Stripe can’t verify the registration status of the charity, you need to collect a proof-of-entity document to enable payouts. Upload it using the documents.company_registration_verification.files parameter.

Universal Beneficial Ownership Verification

After supplying the beneficial owner information, it is checked against the National Registry of Businesses (NRB). Depending on the results of this check, there are three outcomes:

The business is found in the NRB, and the information matches. The account is fully onboarded, and no additional action is required.
The business is found in the NRB, but the information doesn’t match. The account is fully onboarded, and no additional action is required. A discrepancy report is sent to the NRB.
The business isn’t found in the NRB. An attestation must be provided, declaring that the business is registered with the NRB and that the information given to Stripe matches.

In the case where the business isn’t found in the NRB, provide the attestation by setting the date, ip_address, and user_agent in the Account’s company.ownership_declaration hash.

Universal Beneficial Ownership Verification

After supplying the beneficial owner information, it is checked against the National Registry of Businesses (NRB). Depending on the results of this check, there are three outcomes:

The business is found in the NRB, and the information matches. The account is fully onboarded, and no additional action is required.
The business is found in the NRB, but the information doesn’t match. The account is fully onboarded, and no additional action is required. A discrepancy report is sent to the NRB.
The business isn’t found in the NRB. An attestation must be provided, declaring that the business is registered with the NRB and that the information given to Stripe matches.

In the case where the business isn’t found in the NRB, provide the attestation by setting the date, ip_address, and user_agent in the Account’s company.ownership_declaration hash.

Additional information on the account

Additional information on the individual

Depending on the situation, you might need to collect a scan of an ID document, an address document, or both to enable payouts. That can happen if Stripe can’t verify the individual or if there are possible concerns about sanctions. In some cases, depending on various calculated risk factors, Stripe can use Simplified Due Diligence and request only one document for verification at a later time.

Collect ID information using the individual.verification.document.front and individual.verification.document.back parameters, and address information using the verification.additional_document.front and verification.additional_document.back parameters.

Additional information on the representative

A person known as a representative must activate this connected account. The representative must be a beneficial owner who is authorized to sign for the company. Indicate this relationship to Stripe by setting relationship.executive to true, or, if the representative owns 25% or more of the company, by setting relationship.owner to true.

You might need to collect a scan of an ID document and an address document to enable payouts. That can happen if Stripe can’t verify the representative’s provided information or if there are possible concerns about sanctions. In some cases, depending on various calculated risk factors, Stripe can use Simplified Due Diligence and request only one document for verification at a later time.

Additionally, for partnerships you must provide a relationship.percent_ownership value.

You can collect ID information with the verification.document.front and verification.document.back parameters.

Additional information on directors

For companies, excluding partnerships, you must collect information on all directors. Directors are members of the governing board of the company. When you have finished collecting the required information from all directors, or if your company doesn’t have any directors, you must inform Stripe by setting company.directors_provided to true.

You might need to collect a scan of an ID document and an address document to enable payouts. That can happen if Stripe can’t verify the director’s provided information or if there are possible concerns about sanctions. In some cases, depending on various calculated risk factors, Stripe can use Simplified Due Diligence and request only one document for verification at a later time.

You can collect ID information using the verification.document.front and verification.document.back parameters, and address information using the verification.additional_document.front and verification.additional_document.back parameters.

Additional information on beneficial owners (for both executives and owners)

You must collect information on all beneficial owners. Beneficial owners are persons who exercise significant management control over the company (executives) or who own 25% or more of the company (owners). When you have finished collecting the required information from all beneficial owners, you must inform Stripe by setting both company.owners_provided and company.executives_provided to true.

You might need to collect a scan of an ID document and an address document to enable payouts. That can happen if Stripe can’t verify the beneficial owner’s provided information or if there are possible concerns about sanctions. In some cases, depending on various calculated risk factors, Stripe can use Simplified Due Diligence and request only one document for verification at a later time.

Optionally, you can collect ownership information on each person who owns 25% or more of the company with relationship.owner and relationship.percent_ownership.

Additionally, for partnerships you need to provide a relationship.percent_ownership value for any owners added to the account.

Universal Beneficial Ownership Verification

After supplying the beneficial owner information, it is checked against the National Registry of Businesses (NRB). Depending on the results of this check, there are three outcomes:

The business is found in the NRB, and the information matches. The account is fully onboarded, and no additional action is required.
The business is found in the NRB, but the information doesn’t match. The account is fully onboarded, and no additional action is required. A discrepancy report is sent to the NRB.
The business isn’t found in the NRB. An attestation must be provided, declaring that the business is registered with the NRB and that the information given to Stripe matches.

In the case where the business isn’t found in the NRB, provide the attestation by setting the date, ip_address, and user_agent in the Account’s company.ownership_declaration hash.

Universal Beneficial Ownership Verification

After supplying the beneficial owner information, it is checked against the National Registry of Businesses (NRB). Depending on the results of this check, there are three outcomes:

The business is found in the NRB, and the information matches. The account is fully onboarded, and no additional action is required.
The business is found in the NRB, but the information doesn’t match. The account is fully onboarded, no additional action is required. A discrepancy report is sent to the NRB.
The business is not found in the NRB. A proof of registration document (screenshot of the registration or copy of the confirmation email) is required to be uploaded.

Uploading proof of registration Custom accounts

In the case the business is not found in the NRB, a screenshot of the beneficial owner information from the NRB must be uploaded using the documents.proof_of_registration.files parameter. Set the File’s purpose parameter to account_requirement.:

This request uploads the file and returns a token:

{
  "id": "file_5dtoJkOhAxrMWb",
  "created": 1403047735,
  "size": 4908
}

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

Universal Beneficial Ownership Verification

After supplying the beneficial owner information, it is checked against the National Registry of Businesses (NRB). Depending on the results of this check, there are three outcomes:

The business is found in the NRB, and the information matches. The account is fully onboarded, and no additional action is required.
The business is found in the NRB, but the information doesn’t match. The account is fully onboarded, and no additional action is required. A discrepancy report is sent to the NRB.
The business isn’t found in the NRB. An attestation must be provided, declaring that the business is registered with the NRB and that the information given to Stripe matches.

In the case where the business isn’t found in the NRB, provide the attestation by setting the date, ip_address, and user_agent in the Account’s company.ownership_declaration hash.

Business representative verification

Stripe requires the account representative to undergo enhanced identity verification and address verification.

Enhanced identity verification

Singapore requires using Singpass MyInfo for enhanced identity verification of representatives for all business types. If users don’t have access to MyInfo, they must verify liveness using Stripe Identity.

Successful completion of enhanced identity verification using either SingPass MyInfo or Stripe Identity requires integrating with Connect Onboarding or Embedded Onboarding. If you’re using the Stripe API to onboard connected accounts, you must update your forms to collect the new required verification information from your users, and redirect them to Connect Onboarding at the final stage to complete the enhanced identity verification.

Address verification

Verification of the business representative’s address is required for all businesses. If Stripe can’t verify the address, you must collect a proof of address document.

Proof of authority verification

Stripe needs to verify that the account representative has sufficient authority to open an account on behalf of the legal entity.

If we can’t verify this programmatically, Stripe returns the verification_failed_representative_authority error code. If possible, change the representative to a person with sufficient authority.

If necessary, you can allow a business representative without verifiable authority by having a person with authority authorize them in writing:

Add the person with authority as a Person with the authorizer relationship. You must provide their first name, last name, and identity document.
Have the person with authority sign a Letter of Authorization that permits the business representative to manage the account. They must create the letter using this template.
Provide the signed letter as the documents.company_authorization on the Person representing the business representative.

Additionally, the Letter of Authorization requirement can expose document-related errors such as verification_document_name_mismatch, or verification_document_type_not_supported. Make sure you can handle Document Verification Errors and the New verification error codes.

Proof of authority verification

Stripe needs to verify that the account representative has sufficient authority to open an account on behalf of the legal entity.

If we can’t verify this programmatically, Stripe returns the verification_failed_representative_authority error code. If possible, change the representative to a person with sufficient authority.

If necessary, you can allow a business representative without verifyable authority by having a person with authority authorize them in writing:

Add the person with authority as a Person with the authorizer relationship. You must provide their first name, last name, and identity document.
Have the person with authority sign a Letter of Authorization that permits the business representative to manage the account. They must create the letter using this template.
Provide the signed letter as the documents.company_authorization on the Person representing the business representative.

Legal entity verification

Stripe requires the verification of business name, UEN, and legal entity type. If we can’t verify the existence of the company, you must collect a company document.

Stripe also needs to check that the business type and business structure matches the local government records. When a mismatch in business type or business structure occurs, it generates a verification_legal_entity_structure_mismatch error, and you need to update the business type or structure, or provide a company document to verify the legal entity.

UEN information might be verified with the data made available at https://data.gov.sg under the terms of the Singapore Open Data License version 1.0.

Legal entity verification

Stripe requires the verification of business name, UEN, and legal entity type. If we can’t verify the existence of the company, you must collect a company document.

UEN information might be verified with the data made available at https://data.gov.sg under the terms of the Singapore Open Data License version 1.0.

Ultimate beneficial ownership verification

The ultimate beneficial ownership verification requirements depend on the user’s business type.

Private Companies

Stripe defines and attempts to identify any individual with 25% or more ownership as the ultimate beneficial owner (UBO). We recommend using Stripe-hosted or Embedded Onboarding to allow your users to preview and confirm the owners. Alternatively, you can collect and add all UBOs to the account as Persons with the owner relationship.

If Stripe can’t determine these individuals, a company must submit a proof of ultimate beneficial ownership document to attest to their ownership structure. This must include proof of ownership documents for any holding companies owning 25% or more shares of the connected account. Stripe-hosted or embedded onboarding automatically seeks to collect these documents, or you can collect and submit them using the Accounts API. You must add all UBOs listed on the proof of ultimate beneficial ownership to the account.

Note

Connected accounts can submit a single ultimate beneficial owner attestation as an alternative to one document for the business and another for each holding company with significant ownership.

If the company has no owners with 25% or more ownership, all directors listed on government records (and available for preview on Stripe-hosted or embedded onboarding) are considered to be the UBOs and you must add them to the account.

Partnerships

Partnerships must verify the relationship between the business and all partners, managers, and any other individual with 25% or more ownership. You must add all such people to the account as Persons with the owner relationship.

Exemptions

In certain situations, a business entity might not need to declare its ownership. To qualify for an exemption, you must provide a legitimate reason in the company.ownership_exemption_reason field. Valid reasons for exemption include:

qualified_entity_exceeds_ownership_threshold: If a government, publicly listed company, or financial institution owns at least 75% of the business, the business is exempt from providing ownership details.
qualifies_as_financial_institution: Businesses that are financial institutions regulated by the Monetary Authority of Singapore are exempt from sharing ownership details.

After submitting an exemption reason, we review the business entity’s details. During this review, the requirement moves to requirements.pending_verification. If Stripe determines that the business entity doesn’t qualify for the exemption, we display an error message, and the ownership requirement remains:

{
  "id": "{{CONNECTED_ACCOUNT_ID}}",
  "requirements": {
    "past_due": [
      "documents.proof_of_ultimate_beneficial_ownership.files",
    ],
    "alternatives": [
      {
        "original_fields_due": [
          "documents.proof_of_ultimate_beneficial_ownership.files",
        ],
        "alternative_fields_due": [
          "company.ownership_exemption_reason",
        ]
      }
    ],
    "errors": [
      {
        "code": "verification_rejected_ownership_exemption_reason",
        "reason": "The ownership exemption reason was rejected.",
        "requirement": "company.ownership_exemption_reason"
      }
    ],
    ...
  },
  ...
}

Integration details

You must add UBOs and directors to the account with the owner or director position in the API. Private companies, private partnerships, and non-profits require proof of beneficial ownership. When we can’t successfully verify the UBO, you need to collect an ID Document for the unverified UBO.

If Stripe determines that the account is missing owners, directors, or documentation of holding companies, the documents.proof_of_ultimate_beneficial_ownership.files field will be returned in requirements. You can find a complete list of acceptable documents at Acceptable Verification Documents.

Additionally, you could be asked to attest that the list of directors is current and correct by setting the following fields in the API:

company.directorship_declaration.ip
company.directorship_declaration.date
(Optional) company.directorship_declaration.user_agent

If a discrepancy in your list of directors is detected, Stripe might request a new declaration by returning the company.directorship_declaration.ip and company.directorship_declaration.date requirements in the requirements field.

Both Stripe-hosted and embedded onboarding display a list of missing owners and directors, and the account user can add them to their account by clicking on them. Adding the suggested individuals fulfills the UBO requirement for companies without any holding companies in their ownership structure. For companies with holding companies, Stripe attempts to verify their owners. If we can’t, we prompt the account user to upload either an ultimate beneficial owner attestation document or relevant ownership documents to determine the account’s ultimate beneficial owners. (This also applies to other business types, such as non-profits.)

Accounts with missing beneficial owners have a verification_missing_owners error code in the errors hash of requirements. Similarly, accounts with missing directors have a verification_document_directors_mismatch error code. Lastly, accounts where Stripe requires additional information regarding their ownership have a verification_requires_additional_proof_of_registration error code.

{
  "id": "{{CONNECTED_ACCOUNT_ID}}",
  "requirements": {
    "past_due": [
      "documents.proof_of_ultimate_beneficial_ownership.files",
    ],
    "errors": [
      {
        "code": "verification_missing_owners",
        "requirement": "documents.proof_of_ultimate_beneficial_ownership.files",
        "reason": "..."
      },
      ...
    ],
    ...
  },
  ...
}

Ultimate beneficial ownership verification

In the case of non-profits, all key executives and directors are considered UBOs. This includes:

President
Director
CEO
Treasurer
Secretary or General Secretary
Chairman
Trustee
Newly added positions
And any of these positions in an Assistant, Deputy, or Vice capacity.

Stripe attempts to identify all directors and key executives of charities registered in Singapore, which you can preview and confirm in Stripe-hosted or embedded onboarding. All other non-profits must provide a proof of ultimate beneficial ownership document and you must add the listed individuals to the account with the director position in the API.

Integration details

You must add all UBOs of non-profits to the account with director position in the API. When we can’t successfully verify the UBO, you need to collect an ID Document for the unverified UBO.

If Stripe determines that the account is missing owners, directors, or documentation of holding companies, the documents.proof_of_ultimate_beneficial_ownership.files field becomes due. You can find a complete list of acceptable documents for Singapore at Acceptable Verification Documents.

Both Stripe-hosted and embedded onboarding display a list of missing owners and directors, and the account user can add them to their account by clicking on them. Adding the suggested individuals fulfills the UBO requirement for companies without any holding companies in their ownership structure. For companies with holding companies, Stripe attempts to verify its owners. If we can’t, we prompt the account user to upload either an ultimate beneficial owner attestation document or relevant ownership documents to determine the account’s ultimate beneficial owners. (This also applies to other business types, such as non-profits.)

Non-profits with missing beneficial owners have a verification_document_directors_mismatch error code.

{
  "id": "{{CONNECTED_ACCOUNT_ID}}",
  "requirements": {
    "past_due": [
      "documents.proof_of_ultimate_beneficial_ownership.files",
    ],
    "errors": [
      {
        "code": "verification_document_directors_mismatch",
        "requirement": "documents.proof_of_ultimate_beneficial_ownership.files",
        "reason": "..."
      },
      ...
    ],
    ...
  },
  ...
}

Closure of unverified accounts

As required under Singapore’s Payment Services Act, we’re permanently closing Singapore accounts that remain unverified for over 120 business days. These are accounts whose charges or payouts have already been suspended, so this closure affects only inactive accounts.

To help you identify affected accounts, we upload monthly reports titled “Unverified account list” to your Dashboard under the Compliance and documents section, where you can find the list of impacted accounts and their requirement deadlines. Any accounts closed in the last month are in the report titled “Closed unverified account list.”

We’ll close any account that hasn’t been verified by its designated deadline. The account owner needs to provide the missing verification information before the deadline to keep the account open. If the information is provided after the deadline has passed, we’ll release any remaining balance to the account holder’s bank account, but we won’t be able to reactivate their Stripe account.

Stripe sends emails to Standard and Express accounts that remain unverified for too long, to inform them of the impending closure and to remind them to update their account details. Stripe won’t communicate with Custom connected accounts directly. That means you, as the platform, can contact them to avoid account closures.

Accounts that are closed under this process have their disabled_reason set to rejected.other.

Additional identity verification

To comply with regulatory requirements in Thailand, we require additional identity verification for certain connected accounts. This entails taking a selfie and uploading an ID document using Stripe Identity. Your platform needs to integrate with Connect Onboarding to satisfy this identity verification requirement.

Additional identity verification applies to the representatives and beneficial owners of connected accounts belonging to individuals, sole proprietors and unregistered partnerships.

Warning

If you don’t integrate with Connect Onboarding, you won’t be able to onboard connected accounts subject to additional identity verification.

Registered address requirement

The registered address requirement refers to the Household Registration address. Please provide an address as per the ‘Tabien Bann’ or Household Registration book, also known as the Blue book for Thai nationals, or Yellow book for non-Thai nationals. To collect a Household Registration address, use the Person’s registered_address parameter.

If the user is neither a Thai national nor resident of Thailand, collect their current residential address with the same parameter instead.

ID number requirement

The ID number requirement refers to the 13-digit code found on the front of a Thai ID card, and secondary ID number requirement refers to the laser code found at the back of a Thai ID card. To collect a Thai ID number, use the Person’s id_number parameter, and to collect a laser code use the id_number_secondary parameter.

These requirements are only applicable to Thai nationals, so leave the parameters empty if the user isn’t a Thai national.

Additional information on the individual

If Stripe can’t verify the individual, or if they’re not a Thai national, you need to collect a scan of an ID document. To collect an ID document, use the Account’s individual.verification.document.front and individual.verification.document.back parameters.

Additional information on the representative

If Stripe can’t verify the account representative, or if they’re not a Thai national, you need to provide a scan of an ID document. To collect an ID document, use the Person’s verification.document.front and verification.document.back parameters.

Additional information on beneficial owners

Accounts belonging to companies and registered partnerships are required to provide information on all beneficial owners. A beneficial owner is defined as any individual who owns 25% or more shares of the business. If there is no such person, then any individual who exercises significant control over the company is considered a beneficial owner. Otherwise, please provide information on any individual holding the position of senior management.

If Stripe can’t verify a beneficial owner, or if they’re not a Thai national, you need to provide a scan of an ID document. To collect an ID document, use the Person’s verification.document.front and verification.document.back parameters.

Additional information on the company

If Stripe can’t verify the company, you need to provide a scan of a company verification document issued less than 6 months ago. To collect a company verification document scan, use the Account’s company.verification.document.front and company.verification.document.back parameters.

Additional tax information

If Stripe can’t verify the company.tax_id, upload a copy of an IRS Letter 147C document or an IRS SS-4 confirmation letter using the company.verification.document.front parameter. The document must include the connected account’s company.name and company.tax_id.

Additional information on the account

Enabling card payments requires a validated city, state, and postal code for company.address. It also requires the company.tax_id (EIN) within 30 days or before 1,500 USD in payments, whichever comes first. If Stripe can’t verify the EIN before the deadline, we disable card payments.

Enabling payouts, requires a validated full company.address and company.tax_id (EIN) within 30 days. Stripe disables payouts if we haven’t verified the full address or the company.tax_id before the deadline.

Additional information on the individual

Enabling card payments requires a validated city, state, and ZIP code for individual.address.

Enabling payouts requires a validated full individual.address. Stripe disables payouts if we haven’t verified the full address within 30 days.

If the individual fails verification with their ssn_last_4, then enabling card payments requires verifying their full SSN and their identity. Upload their full SSN using the individual.id_number parameter.

Additional information on the representative

A Person known as a representative must activate this connected account. The representative must have significant responsibility to control, manage, or direct the organization, and must be authorized by the organization to agree to Stripe’s terms. The representative must be either an owner or an executive, which you specify by setting relationship.owner or relationship.executive to true.

If the representative fails verification with ssn_last_4, then enabling card payments requires verifying their full SSN and their identity. Upload their full SSN using the person.id_number parameter.

If Stripe can’t verify the representative, or if the person doesn’t have an SSN, then enabling card payments requires you to provide a scan of an ID document. Upload the front and back of the document using the verification.document.front and verification.document.back parameters.

Additional information for minors

If the account representative is a minor, you must verify the minor’s legal guardian. A legal guardian is a Person object on the account with relationship.legal_guardian set to true. Additionally, the legal guardian must provide their information and sign the Stripe terms of service, which we store on the Person object that represents the guardian. Store the legal guardian’s terms of service acceptance in the additional_tos_acceptances hash.

If the legal guardian fails verification with their ssn_last_4, then enabling card payments requires verifying their full SSN and their identity. Upload their full SSN using the person.id_number parameter.

If Stripe can’t verify the legal guardian, or if the person doesn’t have an SSN, then enabling card payments requires you to provide a scan of an ID document. Upload the front and back of the document using the verification.document.front and verification.document.back parameters.

Additional information on owners

You must collect information on all owners who have 25% or more ownership of the company, represented by Person objects on the account. When you finish collecting the required owner information, you must set company.owners_provided to true.

If the company has any unverified 25% owners, Stripe can disable payouts on the connected account when it reaches 750,000 USD in charges. To avoid disabling payouts, you must collect the following information for all 25% owners:

If Stripe can’t verify an owner, or if an owner doesn’t have an SSN, you must provide a scan of an ID document for them. Upload the front and back of the document using the verification.document.front and verification.document.back parameters.

Optionally, you can collect company ownership information by setting relationship.owner to true and relationship.percent_ownership to the person’s ownership percentage. If you don’t specify relationship.percent_ownership, it defaults to 25%.

Supported business structures

Optionally, you can provide information on the legal structure of your connected account’s business using the company.structure parameter.

Stripe supports the following business structures for privately held companies:

multi_member_llc
single_member_llc
private_partnership
private_corporation
unincorporated_association

Stripe supports the following business structures for publicly traded companies. If you assign either of these structures to the business, then the representative doesn’t need to be an owner or an executive, and you don’t need to provide information on additional owners.

public_corporation
public_partnership

Supported business structures

Optionally, you can provide information on the legal structure of your connected account’s business using the company.structure parameter.

Stripe supports the following business structures for government entities:

governmental_unit
government_instrumentality

If your connected account is an instrumentality with tax-exempt status, you can set the company.structure to tax_exempt_government_instrumentality.

Supported business structures

While uncommon, there are circumstances where an individual business operates and is treated more like a company, such as a single-member LLC. For these accounts, you can optionally provide information on their legal structure using the company.structure parameter.

If your connected account’s business has only one member or owner, and is registered as an LLC with a US state, you can set the business_type to company and the company.structure to single_member_llc. You collect the same required information, except you use the company hash and the Persons API instead of the individual hash. In that case, you map requirements in the individual hash to the corresponding properties of the account’s representative. For example, set first_name on the representative’s Person instead of individual.first_name on the Account.

If your connected account has a business identification (for example, a tax ID separate from their personal ID, or a business address different than their home address), you can set the business_type to company and the company.structure to sole_proprietorship. You collect the same required information, except you use the company hash and the Persons API instead of the individual hash In that case, you map requirements in the individual hash to the corresponding properties of the account’s representative. For example, set first_name on the representative’s Person instead of individual.first_name on the Account.

Supported business structures

Optionally, you can provide information on the legal structure of your connected account’s business using the company.structure parameter.

Stripe supports the following business structures for non-profit organizations:

incorporated_non_profit
unincorporated_non_profit

The US government grants tax-exempt status to certain government entities that it considers to be non-profit. If your connected account is an instrumentality with tax-exempt status, you can set the business_type to government_entity and the company.structure to tax_exempt_government_instrumentality. You must then collect the appropriate verification requirements.

Tax reporting information

By default, the requirements for transfers don’t collect all information at the appropriate thresholds to file IRS Form 1099-K or Form 1099-MISC. If your business has US federal 1099 filing requirements and plans to file these through Stripe, request the appropriate tax reporting capability and make sure to collect the necessary information from your users.

Threshold information

In addition to the onboarding requirements, payouts require that you provide your connected account’s company.tax_id (EIN) before its charges reach a certain threshold. The threshold is either 10,000 USD or 3,000 USD, depending on your industry and Stripe’s review of your platform profile. If Stripe can’t verify your connected account’s EIN before it reaches the threshold, we disable payouts.

Threshold information

In addition to the onboarding requirements, payouts require that you provide the following information for your connected account before its charges reach a certain threshold. The threshold is either 10,000 USD or 3,000 USD, depending on your industry and Stripe’s review of your platform profile. If Stripe can’t verify this information before the account reaches the threshold, we disable payouts.

individual.dob.day
individual.dob.month
individual.dob.year
individual.ssn_last_4

Payments threshold information

When a connected account with card_payments reaches 500,000 USD in lifetime charges, we require a full SSN for them to continue accepting payments. If they’ve already provided the full SSN, they don’t have to provide it again.

For connected accounts with business_type set to individual, and where the owner isn’t a minor, update the Account’s individual.id_number. For other accounts, which have persons with relationship.legal_guardian, relationship.representative, or relationship.owner set to true, update the appropriate Person’s id_number.

Support phone number

For accounts without access to a Stripe-hosted dashboard, and where Stripe is responsible for negative balances, activating card_payments requires business_profile.support_phone.

Create forms to collect information
Client-side

As a best practice, organize the required parameters into logical groupings or forms in your onboarding flow. You might wish to encode a mapping between the Stripe parameters and the logical groupings. Suggested logical groupings for parameters are shown in the first column of the example requirements table.

After you encode the required parameters into your application, generate UIs for the parameters corresponding to these requirements. For each parameter, design a UI form that includes:

Parameter label, localized to each supported country and language
Parameter description, localized to each supported country and language
Parameter input fields with data validation logic and document uploading where required

It’s important to architect your application logic to account for the possibility of additional parameters in the future. For example, Stripe might introduce new parameters, new verifications, or new thresholds that you must incorporate into your onboarding flows over time.

Changing any of the factors that determine your connected accounts’ requirements means you must also adjust your collection forms to handle the changed requirements. Country and service agreement type are immutable, while capabilities and business type are mutable.

To change an immutable field, create a new connected account with the new values to replace the existing account.
To change a mutable field, update the connected account.

Include the Stripe Terms of Service Agreement

Your connected accounts must accept Stripe’s terms of service before they can activate. You can wrap Stripe’s terms of service in your own terms of service.

Create a connected account
Server-side

Create an Account where your platform is liable for negative balances, Stripe collects fees from your platform account, and your connected accounts don’t have access to a Stripe-hosted Dashboard. Request any capabilities that your connected accounts need. Prefill the business type and any other available information matching your requirements.

Alternatively, you can create a connected account with type set to custom and desired capabilities.

If you don’t specify the country and service type agreement, they’re assigned the following default values:

The country defaults to the same country as your platform.
The service type agreement (tos_acceptance.service_agreement) defaults to full.

Note

To comply with French PSD2 regulations, platforms in France must use account tokens. An additional benefit of tokens is that the platform doesn’t have to store PII data, which is transferred from the connected account directly to Stripe. For platforms in other countries, we recommend using account tokens, but they aren’t required.

Determine the information to collect
Server-side

As the platform, you must decide if you want to collect the required information from your connected accounts up front or incrementally. Up-front onboarding collects the eventually_due requirements for the account, while incremental onboarding only collects the currently_due requirements.

Onboarding type	Advantages
Up-front	Normally requires only one request for all information Avoids the possibility of payout and processing issues due to missed deadlines Exposes potential risk early when accounts refuse to provide information
Incremental	Accounts can onboard quickly because they don’t have to provide as much information

To determine whether to use up-front or incremental onboarding, review the requirements for your connected accounts’ locations and capabilities. While Stripe tries to minimize any impact to connected accounts, requirements might change over time.

For connected accounts where you’re responsible for requirement collection, you can customize the behavior of future requirements using the collection_options parameter. To collect the account’s future requirements, set collection_options.future_requirements to include.

To implement your onboarding strategy, inspect the requirements hash of the connected account you created. The requirements hash provides a complete list of the information you must collect to activate the connected account.

For incremental onboarding, inspect the currently_due hash in the requirements hash and build an onboarding flow that only collects those requirements.
For up-front onboarding, inspect thecurrently_due and eventually_due hashes in the requirements hash, and build an onboarding flow that collects those requirements.

{
  ...
  "requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "disabled_reason": "requirements.past_due",
    "errors": [],
    "eventually_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "past_due": [],
    "pending_verification": []
  },
  ...
}

Handle liveness requirements

An account can have one or more Person objects with a proof_of_liveness requirement. A proof_of_liveness requirement might require collection of an electronic ID credential such as MyInfo in Singapore, or by using Stripe Identity to collect a document or selfie. We recommend using Stripe-hosted or embedded onboarding to satisfy all variations of the proof_of_liveness requirement.

Stripe-hosted onboarding can complete all variations of proof_of_liveness requirements.

Create an Account Link using the connected account ID, and send the account to the url returned.

The account receives a prompt to complete the proof_of_liveness requirement, along with any other currently due requirements. Listen to the account.updated event sent to your webhook endpoint to be notified when the account completes requirements and updates their information. After the account completes the requirement, the account is redirected to the return_url specified.

Update the connected account
Server-side

Update the Account object with new information as your connected account progresses through each step of the onboarding flow. That allows Stripe to validate the information as soon as it’s added. After Stripe confirms acceptance of our terms of service, any change to the Account triggers reverification. For example, if you change the connected account’s name and ID number, Stripe reruns verifications.

When updating a connected account, you must handle any verification errors or HTTP error codes.

Handle verification errors
Server-side

When the connected account’s data is submitted, Stripe verifies it. This process might take minutes or hours, depending on the nature of the verification. During this process, the capabilities you requested have a status of pending.

Review status

You can retrieve the status of your connected account’s capabilities by:

Inspecting the Account object’s capabilities hash for the relevant capability.
Requesting capabilities directly from the Capabilities API and inspecting the status of the relevant capability.
Listening for account.updated events in your webhook endpoint and inspecting the capabilities hash for the relevant capability.

After verifications are complete, a capability becomes active and available to the connected account. Account verifications run continuously, and if a future verification fails, a capability can transition out of active. Listen for account.updated events to detect changes to capability states.

Confirm that your Connect integration is compliant and operational by checking that the account’s charges_enabled and payouts_enabled are both true. You can use the API or listen for account.updated events. For details on other relevant fields, check the account’s requirements hash. You can’t confirm the integration based on a single value because statuses can vary depending on the application and related policies.

charges_enabled confirms that your full charge path including the charge and transfer works correctly and evaluates if either card_payments or transfers capabilities are active.
payouts_enabled evaluates whether your connected account can pay out to an external account. Depending on your risk policies, you can allow your connected account to start transacting without payouts enabled. You must eventually enable payouts to pay your connected accounts.

You can use the following logic as a starting point for defining a summary status to display to your connected account.

Select a languageRuby
Python
Node.js
 No results
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def account_state(account)
  reqs = account.requirements

  if reqs.disabled_reason && reqs.disabled_reason.include?("rejected")
    "rejected"
  elsif account.payouts_enabled && account.charges_enabled
    if reqs.pending_verification
      "pending enablement"
    elsif !reqs.disabled_reason && !reqs.currently_due
      if !reqs.eventually_due
        "complete"
      else
        "enabled"
      end
    else
      "restricted"
    end
  elsif !account.payouts_enabled && account.charges_enabled
    "restricted (payouts disabled)"
  elsif !account.charges_enabled && account.payouts_enabled
    "restricted (charges disabled)"
  elsif reqs.past_due
    "restricted (past due)"
  elsif reqs.pending_verification
    "pending (disabled)"
  else
    "restricted"
  end
end

accounts = Stripe::Account.list(limit: 10)

accounts.each do |account|
    puts "#{account.id} has state: #{account_state(account)}"
end

Note

You can’t use the API to respond to Stripe risk reviews. You can enable your connected accounts to respond using embedded components, Stripe-hosted onboarding, or remediation links. You can also use the Dashboard to respond to risk reviews on behalf of your connected accounts.

Listen to the account.updated event. If the account contains any currently_due fields when the current_deadline arrives, the corresponding functionality is disabled and those fields are added to past_due.

Create a form with clear instructions that the account can use to correct the information. Notify the account, then submit the corrected information using the Accounts API.

If you plan to create custom flows to handle all your verification errors:

Review the details regarding all possible verification errors and how to handle them.
Test verification states.