Legacy

Moving money using OutboundPayment v2 objects Legacy

Learn how to create outbound payments to move money out of financial accounts to third parties.

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.

OutboundPayment objects represent push-based transfers from your financial account to a third-party external account using ACH or wire transfer or another financial account associated with the same platform instantly using the stripe network. For example, if you want to send money from your financial account to your vendor’s external US bank account, you create an OutboundPayment to move the funds. The receiving account for an OutboundPayment is either an external bank account or a financial account that belongs to a different connected account.

The typical transfer time for outbound payments can range from minutes (when using the Stripe network), same day, to 1-2 business days (when using the ACH network). For more information, see the Money movement timelines guide.

Create an OutboundPayment

Collect required fields

First, get your FinancialAccount ID using the FinancialAccount API. You can also view your available funds.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Then, use the Accounts v2 API to retrieve the recipient account’s recipient configuration and verify that the status of the desired payout method capability is set to active. This ensures you have all the required information to complete a payout. Otherwise, your payout might fail. Learn more about managing recipients.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

{
 "id": "acct_1R826uQgVatBcAVX",
 "object": "v2.core.account",
 "applied_configurations": [
 "recipient"
 ],
 "configuration": {
 "customer": null,
 "merchant": null,
 "recipient": {
 "capabilities": {
 "bank_accounts": {
 "local": {
 "requested": true,
 "status": "active",
 "status_details": []
 },
 "wire": null,
 "instant": null
 },
 "cards": null,
 "stripe_balance": null,
 "paper_checks": null
 },
 "default_outbound_destination": null

You can optionally use the Payout Methods v2 API with the recipient ID to inspect available payout methods. The response contains a list of PayoutMethod objects that a recipient owns. Use the Accounts v2 API to set a PayoutMethod as the default outbound destination with configuration.recipient.default_outbound_destination.

The Stripe-Context header in this request must be the Account ID of the connected account + forward slash + the Account ID of the recipient (for example, acct_111a/acct_111b).

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Submit a payout

Use the OutboundPayments API v2 to make a payout to a recipient. You must provide the following parameters to create a payout:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Submit a payout with PayoutIntents Private preview

Use the Payout Intents API to make a payout to a recipient. You must provide the following parameters to create a payout:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Submit a paper check Private preview

To send a paper check, provide a signature in the delivery_options.paper_check.signature field. Optionally, provide a memo and specify a shipping speed in delivery_options.paper_check.memo and delivery_options.paper_check.shipping_speed fields respectively. You don’t need to use the to.payout_method field when submitting a paper check.

Both delivery_options.paper_check.signature and delivery_options.paper_check.memo are printed on the check.

Command Line

cURL

Add attachments to a paper check

You can include a PDF attachment with a paper check, such as an invoice or receipt. Stripe supports PDF files only. The maximum page count depends on the shipping speed: 5 pages for standard shipping and 50 pages for priority shipping.

Upload the file with the Files API and set purpose to paper_check_attachment. You must include the Stripe-Account header and set it to the connected account ID that owns the financial account.

Command Line

Pass the returned file ID in delivery_options.paper_check.attachment when you create the outbound payment.

Command Line

cURL

Inspect payout status

Call the OutboundPayments API v2 to inspect payouts, including their status. Specify using the OutboundPaymentID in the OutboundPayments API v2 call.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Inspect a PayoutIntent Private preview

Call the Payout Intents API to inspect payouts, including their status. Specify the PayoutIntent ID in the request.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Learn more about managing payouts.

Possible payout statuses

The following table describes the possible payout statuses.

Track status of paper checks

Paper checks have additional information such as tracking details to help you know its location at any time. These fields populate under tracking_details.paper_check.

Statement descriptors

Statement descriptors explain charges or payments on bank statements. By default, a payout recipient sees your account’s statement descriptor.

Customize statement descriptors Public preview

You can customize the descriptor for each payout when you create it.

When creating a payout in the Dashboard, enter a custom statement descriptor in the Statement descriptor field.

Payout amounts

Review the following tables to learn the minimum and maximum payout amounts for each country. Keep in mind the following when considering minimum payout amounts:

• The minimum amount applies regardless of whether the currency is the source or destination currency.
• The minimum amount in the API request must be in minor units . For example, enter 1 USD as 100.
• The source and destination currencies must both pass the minimum payout amounts.

For example, if you’re a US business funding a cross-border payout in USD to a recipient in South Africa who will receive ZAR, you must meet the minimums for both USD (0.01 USD) and ZAR (100 ZAR). If you tried to send 3 USD (passes USD minimum) to a South African recipient, the payout would fail because 3 USD = 55.63 ZAR, which fails the ZAR minimum.

Minimum sending amounts by sender country

The following minimum amounts apply based on your business’s sending country and currency.

1 the related setting supports 6 decimal places, so 1 the related setting = 1000000 expressed in minor units.

Maximum sending amounts by sender country

The following maximum amounts apply based on your business’s sending country, currency, and payout method.

Maximum receiving amounts by recipient currency

The following maximum amounts apply based on the currency your recipient receives.

Minimum receiving amounts by recipient currency

The following minimum amounts apply based on the currency your recipient receives.

the related setting payroll compliance

When sending funds for payroll purposes to recipients in the US with ACH, the related setting rules require the originator to explicitly identify the payouts as such. When sending an OutboundPayment, set the purpose parameter to payroll to ensure compliance with this requirement.

Payout timing

Wire transfer routing numbers

Some banks might use a separate wire transfer routing number that differs from ACH. Consequently, you might receive an error during wire creation if the routing number on the payment method doesn’t support wire transfers. If you receive this error, you need to add a new payment method with your bank’s wire routing number.

RTP routing requirements

Real-Time Payments (RTP) use the same routing numbers as ACH transfers. However, not all banks support RTP. If you receive an error during RTP payout creation, the recipient’s bank might not support RTP, and you should use ACH ( bank_accounts.local) or wire ( bank_accounts.wire) instead.

Create an OutboundPayment to a financial account

To move money between financial accounts, call POST /the relevant part of the product on the origin account and specify the destination account in the destination_payment_method_data parameter. Both financial accounts must be associated with the same platform, but can’t be associated with the same connected account. To transfer money between financial accounts associated with the same connected account, use an OutboundTransfer.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

The body of your request must be x-www-form-urlencoded, but the following JSON defines the data you can send.

Select a language

JSON (commented)

JSON

No results

{
 // The source FinancialAccount. Funds are pulled from this account.
 "financial_account": "{{SOURCE_FINANCIAL_ACCOUNT_ID}}",
 // The amount to send.
 "amount": 1000,
 "currency": "usd",
 // The destination payment method. This parameter is the only way to
 // send an OutboundPayment through the `stripe` network.
 "destination_payment_method_data": {
 "type": "financial_account",

Cancel an OutboundPayment

Use POST /the relevant part of the product/{{the related setting}}/cancel to cancel the OutboundPayment with the associated ID. The OutboundPayment object includes a cancelable parameter with a Boolean value to indicate whether you can cancel the transfer. After an OutboundPayment submits to the network, the cancelable value becomes false and you receive an error from this endpoint for that transfer.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

If successful, the response returns the OutboundPayment object with the status value set to canceled.

{
 "id": "{{OUTBOUND_PAYMENT_ID}}",
 "object": "outbound_payment",
 "livemode": false,
 "created": 123456,
 "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
 "amount": 1000,
 "currency": "usd",
 ...
 "status": "canceled",

Test OutboundPayments

To confirm your integration works, you can simulate sending payouts in a test environment.

Sandboxes

In the Stripe Dashboard, use a sandbox to test functionality without affecting your live integration. Learn more about working in Sandboxes.

1. Create a sandbox environment and switch to it.
2. Enable Issuing and Treasury for platforms on the sandbox in the Dashboard.
3. In the sandbox, create a connected account to start testing.

Use sandbox API key

Use a sandbox API key to test your integration. Sandbox API keys contain the sk_test_ prefix and live mode secret keys contain the sk_live_ prefix. Keys associated with a sandbox can only operate on objects in that sandbox.

1. Navigate to Developers , and click API keys .
2. Under Standard keys , locate your secret test key.

Create recipient and send money

After enabling OutboundPayments on your sandbox and funding the sandbox financial account, you can create recipients and send money to them. Use test payout credentials to test different scenarios in your sandboxes. You can’t use these test accounts in live mode.

Test bank account numbers

If you’re in a sandbox, you can use the related setting as the verification code.

Recipient country:

Test check signatures

Use the following test signature values in the delivery_options.paper_check.signature field to simulate different check send outcomes in your sandbox. All other signature values result in an error.