Recipient creation using the APIPublic preview

Learn how to onboard recipients using the Stripe API.

Build an information collection flow for your recipients to collect recipient and payout method details, and then pass that information to Stripe through our APIs. Your business is responsible for all interactions with your recipients and for collecting all the necessary information to verify them. We update verification requirements as laws and regulations change around the world. Plan on reviewing and updating onboarding requirements on a regular basis to avoid payout failures.

To create a recipient that can receive payouts, you need to create:

An active recipient with the Accounts v2 API
An enabled payout method with the USBankAccount API v2

Create forms to collect information

To make a payout, you need to collect information from your recipient. Create a method or form so your recipients can submit information to you that you then submit to Stripe using the API.

Because verification requirements are a function of legal and regulatory requirements, the information you need to collect might change. Design your application logic for the possibility of additional parameters in the future.

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.

You must specify your intended payout methods with the Accounts v2 API because some methods require additional information about your recipient before we can enable them. 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. To receive these requirements, include requirements, configuration.recipient, and identity in the include array. Otherwise, Stripe returns a null response, regardless of their actual value.

When you create, retrieve, or update an Account, certain fields only populate in the response if you specify them in the include parameter. For any of those fields that you don’t specify, the response includes them as null, regardless of their actual value.

Determine required fields to activate a recipient

Use the response from the Accounts v2 API to inspect the requirements.entries to determine the specific fields you need to submit to Stripe. Any entries that have the restricts_capabilities field are required for the recipient to accept payouts.

{
 "id": "acct_1R9UxIQlxdq9VtNU",
 "object": "v2.core.account",
 "applied_configurations": [
   "recipient"
 ],
 "configuration": {
   "customer": null,
   "merchant": null,
   "recipient": {
     "capabilities": {
       "bank_accounts": {
         "local": {
           "requested": true,
           "status": "restricted",
           "status_details": [
             {
               "code": "requirements_past_due",
               "resolution": "provide_info"
             }
           ]
         },
         "wire": null
       },
       "cards": null,

Submit recipient information to Stripe

After you determine the additional fields you need to submit, use the Accounts v2 API to submit the required information.

Confirm that the recipient is enabled

Use the Accounts v2 API to retrieve an account and inspect the status of the capabilities you’ve requested. The status must be active for a recipient to receive payouts by your specified payout method.

Create payout methods for your recipients

Use the USBankAccount v2 API to submit payout method details to Stripe to enable a payout to a recipient.

USBankAccounts can receive payouts by ACH or wire. If you intend to send payouts by wire, include the fedwire_routing_number. Additional fees apply. See pricing for details.

The Stripe-Context header in this request must be the recipient’s Account ID.

You can also use debit cards as a payout method. However, your recipients must submit their debit card information directly to Stripe. If you’re interested in enabling payouts by debit cards, use the Account Links v2 API to create a shareable form for your user to submit their debit card credentials.

View all payout methods for a recipient

View all of the created payout methods for a recipient. Call the Payout Methods API v2 and provide the recipient ID.

The Stripe-Context header in this request must be the recipient’s Account ID.

The response contains a list of PayoutMethod objects that a recipient owns. Use the PayoutMethod IDs to make a payout using the OutboundPayments API. See Send money for more details.