connect-required-verification-information

Files (1)

• SKILL.md

SKILL.md (first lines)

## Instructions

The human-accessible version of this documentation allows the user to select connected account fields and regions using a form, and then makes API requests to fetch and display the requirements a connected account with the selected configuration and region must provide. Follow these instructions to fetch the same information.

### Interaction contract

Terminology used in this document:

- `field`: a setup input such as `platformCountry`, `accountCountry`, or `capabilities`
- `option`: a presented selectable option for a field
- `value`: the option the user selects, or the free-response value the user provides for a field

Every time you ask the user to provide a value for a field:

- use a multiple-choice question; never stop at a plain free-form prompt or wait for raw chat input
- if you need free user input, instruct the user to use the question’s free-response field
- for long option lists, explicitly say that any value from the full validated list is still accepted through the free-response field
- if the user already provided a valid answer in an earlier message, use that instead of asking again

### Hard rules

You must follow these rules:

- Ask for a field *only* after all of its prerequisite fields are satisfied.
- Collect setup fields progressively as the flow advances.
- Ask for one field at a time, or one group of fields only when they’re dependency-free at that point in the flow.
  - For example, ask for `platformCountry` and `accountCountry` separately: the platform country determines which account countries are valid, so asking both together can produce invalid combinations. But you may ask for `dashboardType`, `tosType`, and `legalEntityType` together in one group because their valid options are already known from the same response.
- If there is ever a conflict between the user’s request and the validated setup, inform the user of the conflict and ask them to revise their setup choices using the [Interaction contract](#interaction-contract). Keep the validated setup aligned with what the user requested without silently dropping the conflict.
- Follow the [Interaction contract](#interaction-contract) for every user question.
- When the number of available options exceeds four, *always* print the full validated reference list before asking the multiple-choice question so the user can see the full option space.
  - When printing countries, always print the full country name followed by its code in parentheses, for example, `Germany (DE)`.
  - In the multiple-choice question, include a small set of suggested options so the user can move forward with immediate clarity. The reference list above remains the authoritative full set.
  - Leave the descriptions for the country suggested options blank.
- For any field with four or fewer valid options, show every valid option directly in the multiple-choice question. Don’t print a separate reference list first.
- Every list of selectable options shown to the user must be pre-validated against all currently known constraints before you display it.
- Never display an option as selectable if you already know it will be removed, rejected, or auto-adjusted later in the flow.
  - Present options that stay valid through the current flow.
- Ask about `capabilities` after `platformCountry`, `accountCountry`, and the downstream validity constraints for that setup are resolved.
- *Only* ask about `orrProgram` when it is present in the public `programs` returned for the validated setup.
- If the `businessStructure` map for the chosen `legalEntityType` is empty or contains exactly one key `nil`, skip `businessStructure`. Otherwise, ask for `businessStructure` and always allow a `none` option or leave unselected as a suggested option in the multiple-choice question.
- If the user decides to change an earlier choice like `platformCountry`, you must invalidate and re-check all downstream fields before continuing.
- Keep the dependency chain implicit. Share the information the user needs to make progress and keep the experience simple.
- Use external-facing language when talking to the user. See below to translate the internal API terminology.

#### Internal fields -> External language

| Internal field | External language |
| --- | --- |
| `apiVersion` | Accounts API version |
| `platformCountry` | Platform country |
| `accountCountry` | Account country |
| `dashboardType` | Dashboard type |
| `tosType` | Service agreement |
| `legalEntityType` | Business type |
| `businessStructure` | Business structure |
| `capabilities` | Capabilities |
| `orrProgram` | Requirements update |
| `eu2025` | Europe |

### Dependency chain

You must follow this dependency chain exactly:

```mermaid
flowchart TD
  apiVersion["apiVersion"] --> capabilities
  platformCountry --> accountCountry["accountCountry"]
  accountCountry --> dashboardType["dashboardType"]
  accountCountry --> tosType["tosType"]
  accountCountry --> legalEntityType["legalEntityType"]
  legalEntityType --> businessStructure["businessStructure (optional)"]
  accountCountry --> capabilities["capabilities"]
  accountCountry --> orrProgram["orrProgram (only if returned)"]
  tosType --> capabilities
  apiVersion --> capabilities
  dashboardType --> finalRequest["final requirements request"]
  apiVersion --> finalRequest
  platformCountry --> finalRequest
  accountCountry --> finalRequest
  tosType --> finalRequest
  legalEntityType --> finalRequest
  businessStructure --> finalRequest
  capabilities --> finalRequest
  orrProgram --> finalRequest
```

Interpret the diagram literally:

- Ask for a node *only* after all of its incoming dependencies are resolved.
- Always ask the user for `apiVersion` first. Recommend `v2` by default.

### Inputs you eventually need

By the time you make the final requirements request, you must have validated values for all of the following fields:

- `apiVersion`: `v1` or `v2`
- `platformCountry`
- `accountCountry`
- `dashboardType`
- `tosType`
- `legalEntityType`
- `capabilities`: at least one capability must be selected

You also must have asked for the following optional fields, if they’re applicable:

- `businessStructure`: ask only when `legalEntityType` isn’t `individual`
- `orrProgram`: ask only when present in the public `programs` list for that validated setup

### Resolve capabilities

Use this algorithm whenever you build or validate the capability list:

1. Start from `country_map[accountCountry].capabilities`.
2. Apply `tosType` rules:
   - if `tosType=recipient`, force `transfers` and remove all other capabilities except `crypto_transfers`, which may be available in rare cases
   - if `apiVersion=v1` and `crypto_transfers` is selected, also include `transfers`
3. If `apiVersion=v2`, drop any capability not present in `get-v2-supported-v1-capabilities`.
4. Show the user the filtered capability list. When the user explicitly asks about a filtered-out capability, clearly explain that the asked-for capability is unavailable for the current setup.
5. If the filtered list is empty, tell the user that no capabilities are supported for the current setup and ask them to revise earlier setup choices using the [Interaction contract](#interaction-contract) before making the final requirements request.

From stripe/ai, MIT.

More from stripe/ai