Future requirements

The Future Requirements API feature allows you to preview upcoming new requirements for your connected accounts that are on the card_payments or transfers capabilities, before the requirements go into effect. This helps you more clearly see how changing regulations impact your platform overall, and allows you to collect any additional information from your connected accounts to ensure their capabilities remain active.

Specifically, Future Requirements introduces the future_requirements hash to the Account object. future_requirements is a hash that performs the same function as the requirements hash, but for upcoming requirements that haven’t gone into effect yet. The requirements in future_requirements become active and transition to the requirements hash on the future_requirements[current_deadline].

Stripe uses future_requirements to introduce new onboarding requirements. Because you might see unfamiliar requirements strings as a result of the new onboarding requirements, we recommend not integrating your update forms directly against the hash.

Stripe recommends collecting future_requirements with Connect Onboarding, which enables Stripe to assist you in collecting identity information from your connected accounts. If you don’t use Connect Onboarding, you must implement the identity verification user flows for any future requirements.

New requirements will affect a subset of your connected accounts, depending on their country, business type, and the capabilities they’ve requested. Check your Connect updates dashboard to see which of your connected accounts they affect.

Updating your integration for future_requirements involves two steps:

Step 1: Update onboarding of new accounts

If you haven’t already, we recommend integrating our conversion-optimized Connect Onboarding for Custom Accounts at no additional cost. This is the simplest path to completing your update. With Connect Onboarding, we automatically collect future requirements as you onboard new accounts.

Connect Onboarding also enables you to keep your onboarding experience up-to-date and optimized in each region where your platform does business, without additional development work.

If you’re not using Connect Onboarding, update your onboarding forms to collect the newly required information for US accounts. The aim is to have future_requirements.currently_due empty after your onboarding flow, which ensures the least amount of disruption.

Beginning on the date listed in your dashboard, all newly created accounts in an affected region will receive the new requirements in their requirements hash and will no longer see requirements in future_requirements.

Step 2: Collect requirements from existing accounts

Your existing accounts may require additional information to remain in good standing. Check your Connect updates dashboard to see which accounts have outstanding requirements. To preview the upcoming requirements that aren’t satisfied through the API yet, view the contents of an account’s future_requirements. Then direct your users to Connect Onboarding, and we’ll collect any additional requirements.

If you’re not using Connect Onboarding, you’ll need to reach out to your existing accounts and collect any additional requirements directly.

Beginning on the date listed in your dashboard, future_requirements for all affected accounts transition to requirements.currently_due and need to be satisfied in order to continue receiving payouts and payments.

Below are region specific updates to be aware of.

Simulating future_requirements enforcement

Stripe provides an API to simulate enforcement of existing accounts that have outstanding future requirements at the listed enforcement date in your Connect updates dashboard.

First, create a test mode account using your test mode API key, prior to the enforcement date for new accounts.

curl -X POST https://api.stripe.com/v1/accounts \
  -H "Stripe-Version: 2019-02-19" \
  -u {{PLATFORM_TESTMODE_SECRET_KEY}}: \
  -d type=custom \
  -d country=US \
  -d business_type=individual \
  -d "capabilities[card_payments][requested]=true"
  -d "capabilities[transfers][requested]=true"

Confirm that future_requirements is populated in the response:

{
  "id": "acct_123",
  "object": "account",
  ...
  "future_requirements": {
    "current_deadline": 1656608400,
    "currently_due": [
      "company.tax_id"
    ],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [
      "company.tax_id"
    ],
    "past_due": [],
    "pending_verification": []
  }
}

To simulate enforcement at the future_requirements[current_deadline] date, update the account’s email with the string enforce_future_requirements anywhere in its value:

curl https://api.stripe.com/v1/accounts/acct_123 \
  -H "Stripe-Version: 2019-02-19" \
  -u {{PLATFORM_TESTMODE_SECRET_KEY}}: \
  -d "email=enforce_future_requirements@example.com"

Confirm that the response contains an empty future_requirements hash and a populated requirements hash:

{
  "id": "acct_123",
  "object": "account",
  ...
  "requirements": {
    "current_deadline": 1656608400,
    "currently_due": [
      "company.tax_id"
    ],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [
      "company.tax_id"
    ],
    "past_due": [],
    "pending_verification": []
  },
  "future_requirements": {
    "due_by": null,
    "disabled_reason": null,
    "fields_needed": [],
    "errors": [],
    "pending_verification": []
  }
}