Stripe-hosted recipient creationPublic preview

Learn how to onboard recipients using a Stripe-hosted form.

Use Stripe’s hosted web form to collect recipient information, which renders dynamically based on the capabilities, country, and payment methods for each recipient.

Use the Account Links API to programmatically generate links to collect information with Stripe-hosted forms, which renders dynamically based on the capabilities, country, and payment methods for each recipient, and that you can customize with your business name, brand colors, and icon. Your recipients complete the hosted form and submit required details, including payout credentials (for example, bank account and routing number) directly to Stripe.

Recipient enters their information in the form

Recipient agrees to connect their payout credientials to Stripe

A success screen shows the recipient that they're ready to receive payouts

Supported browsers

Stripe-hosted collection supports desktop and mobile browsers that are:

The last 20 major versions of Chrome and Firefox
The last 2 major versions of Safari and Edge
The last 2 major versions of mobile Safari on iOS
Not iframe environments

Customize the collection form

To customize Stripe-hosted forms, go to the Business brand settings page in the Dashboard to include your business name, color, and icon.

Create a recipient

Use the Accounts v2 API to create your recipient. You must provide the following parameters to create the Account ID:

Required information	Parameter
Recipient’s country	`identity.country`
Recipient’s type of business	`identity.entity_type`
Recipient’s email	`contact_email`
The display name for the account. It appears in the Stripe Dashboard and on any invoices that you send to the account.	`display_name`
Payout methods you want to enable	`configuration.recipient.capabilities`

Private preview

Making payouts to users outside the US is in private preview. If you’re interested in getting access,

enter your email.

Using the Accounts v2 API, you must specify your intended payout methods because some methods require additional information about your recipient to be enabled. The methods you enable using the capabilities parameter determine information that you need to collect for your recipient (for example, configuration.recipient.capabilities.bank_accounts.local for a US recipient requires you to submit an account and routing number).

Payout method	API parameter	Description
Local bank	`configuration.recipient.capabilities.bank_accounts.local`	Allows the Account to receive OutboundPayments over local bank networks, such as ACH or FPS.
Bank wire	`configuration.recipient.capabilities.bank_accounts.wire`	Allows the Account to receive OutboundPayments over wire networks, such as Fedwire or SWIFT.
Cards	`configuration.recipient.capabilities.cards`	Allows the Account to receive OutboundPayments over debit card networks, such as Visa Direct or Mastercard Send.

A recipient can have multiple payout methods enabled. Not all payout methods are available for recipients in all countries. See the full list of available payout methods by country.

After you add these fields and requested payout methods, Stripe determines the additional information required in the API response that you need to submit to make the recipient ready to receive payouts.

Create a shareable link

Create a shareable link using the Account Link API. You send this link to your recipient, who then has access to the collection form to submit required information directly to Stripe. Each AccountLink URL expires 10 minutes after generation and can be used only once. If your recipient clicks the AccountLink after the 10 minute window, they’re redirected to the refresh.url for security reasons. After your recipient provides their information, the AccountLink redirects to the return.url.

Private preview

Interested in verifying your recipients? After recipients share their payout method details in Stripe-hosted forms, use the Financial Connections API to view and confirm the ownership details associated with the linked account. If you’re interested in getting access, enter your email.

To create a shareable link, include the following parameters:

account: The recipient’s account ID, which you can get using the Accounts v2 API
use_case.type: If you’re collecting the recipient’s information for the first time, specify account_onboarding.
use_case.account_onboarding.configurations: Set to recipient.
use_case.account_onboarding.return_url: The page Stripe redirects the recipient to when the AccountLink has already been visited, has expired, or is otherwise invalid.
use_case.account_onboarding.refresh_url: The page Stripe redirects the recipient to when they complete or leave the information collection form.

The following request creates an AccountLink for purposes of collecting a recipient’s information for the first time:

Authenticate the recipient in your application before redirecting them to this URL.

Private preview

Interested in additional authentication tools? Stripe also offers a one-time passcode feature to reauthenticate your recipient by sending an authentication code to their email, and then redirecting them to a new AccountLink. If you’re interested in getting access, enter your email.

Confirmation of Payee check UK only

We require a Confirmation of Payee check before paying UK recipients. Perform this check when you create the bank account, or use a separate API call.

Provide the following parameters in your request to /v2/payment_methods/gb_bank_accounts:

API parameter	Required	Description
`account_number`	Yes	The bank account’s account number.
`sort_code`	Yes	The bank account’s sort code (numeric only).
`confirmation_of_payee`	No	Determines whether to check your recipient’s bank account.

The Stripe-Context header in these requests must be the recipient’s Account ID.

The following is an example response:

{
  "id": "gbba_123",
  "object": "payment_methods.gb_bank_account",
  "bank_account_type": "checking",
  "bank_name": "Test Bank",
  "created": "2023-05-15T16:29:15.738Z",
  "deactivated": false,
  "last4": "2345",
  "sort_code": "108800",
  "confirmation_of_payee": {
    "result": {
      "created": "2024-10-18T19:19:31.000Z",
      "match_result": "mismatch",
      "matched": {
        "business_type": null,
        "name": ""
      },
      "message": "The provided information does not match the information the bank has on file for this account.",
      "provided": {
        "business_type": "business",
        "name": "John Smith"
      }
    },
    "status": "awaiting_acknowledgement"
  },
}

If the Confirmation of Payee result is a match, you can immediately send funds to this destination. If the result is a partial match, non-match, or the service is unavailable, you must acknowledge the result first:

Review these bank accounts to make sure they’re correct before acknowledging. You can also review non-matching bank accounts in the Dashboard.

Confirm recipient is enabled

For a recipient to accept payouts, you must collect information about the recipient and the intended payout methods. You can determine if a recipient is ready to accept payouts using the Dashboard or the Accounts v2 API.

Navigate to Recipients and select the recipient.
Confirm that no additional information is required. A banner on the page displays if we require additional information from the recipient (for example, “Information needed” or “Default bank account not set”). Otherwise, the recipient’s information collection is complete.
Confirm that at least one payout method is enabled under Payout Methods. If not, you need to collect a payout method either by sharing another link or using the API. To create another shareable link, use the Account Links API again.

Make updates to an existing recipient

You can allow recipients to update their information in the Stripe-hosted form by creating another shareable link with the Account Links API.

To create a new shareable link, include:

account: The recipient’s account ID, which you can get using the Accounts v2 API
use_case.type: Specify account_update.
use_case.account_onboarding.configurations: Set to recipient.
use_case.account_onboarding.return_url: The page Stripe redirects the recipient to after the AccountLink has already been visited, has expired, or is otherwise invalid.
use_case.account_onboarding.refresh_url: The page Stripe redirects the recipient to when they have completed or left the information collection form.

Similar to the AccountLink used to create the recipient, the URL expires after 10 minutes and can be used only once. If your recipient clicks the AccountLink beyond the 10 minute window, we redirect them to the refresh.url for security reasons.