Legacy
Manage external recipients Legacy
Learn how to manage external recipients using v2 APIs.
Legacy integration
The v1 version of Treasury for platforms is a legacy integration that doesn’t support many of the features introduced in Treasury for platforms v2. Don’t build a new v1 integration.
When paying out to others using the Outbound Payments v2 API, represent each recipient with an Account that has the recipient configuration and at least one payout method containing their payment credentials. By storing recipients and their credentials, you don’t need to add them manually to each outbound payment.
You can build an interface to collect recipient information in a few different ways:
- Recipient-facing, as a shareable public link
- Internal, where your connected accounts can enter recipient information (for example, if they’re paying a bill and have an invoice with the recipient details)
Your business is responsible for all interactions with your recipients and for collecting all the necessary verification information. Stripe updates verification requirements as laws and regulations change. Review and update onboarding requirements on a regular basis to avoid payout failures.
Create a recipient
Use the Accounts v2 API to create your recipient. You must provide the following parameters:
| 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
Cross-border payouts for US senders is available in private preview for Stripe Treasury for platforms. 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 the related setting. |
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.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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": "{{CONNECTED_ACCOUNT_ID}}",
"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,
"instant": null
},
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.
Command Line
cURL
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 Connected account ID/Recipient ID (for example, acct_111a/acct_111b).
Command Line
cURL
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 Connected account ID/Recipient ID (for example, acct_111a/acct_111b).
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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.