Moving money with Treasury using OutboundPayment objects

Use POST /v1/treasury/outbound_payments to create an OutboundPayment. Among the request’s possible parameters, the following are required:

• amount: Amount in cents to pay.
• currency: Three-letter ISO currency code (only usd supported).
• financial_account: The source financial account funds are sent from.
• destination_payment_method or destination_payment_method_data: Information about the destination of funds for the payment.
  • With destination_payment_method, you must first set up the PaymentMethod for outbound flows using a SetupIntent. You must also specify the customer ID that matches the Customer object the PaymentMethod is attached to. Alternatively, you can use an existing legacy BankAccount attached to the Customer in place of a PaymentMethod.
  • With destination_payment_method_data, you can specify payment method details inline. You can use this to specify bank account details or when you’re sending funds to another financial account over the Stripe network.

Use POST /v1/treasury/outbound_payments to create an OutboundPayment from the financial account identified by the ID in the financial_account parameter value of the body. The following request adds statement_descriptor and destination_payment_method_data information.

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d amount=2000 \
  -d currency=usd \
  -d statement_descriptor=payment_1 \
  -d "destination_payment_method_data[type]"=us_bank_account \
  -d "destination_payment_method_data[us_bank_account][account_holder_type]"=individual \
  -d "destination_payment_method_data[us_bank_account][routing_number]"=110000000 \
  -d "destination_payment_method_data[us_bank_account][account_number]"=1234567890 \
  --data-urlencode "destination_payment_method_data[billing_details][email]"="jenny@example.com" \
  -d "destination_payment_method_data[billing_details][phone]"=7135551212 \
  -d "destination_payment_method_data[billing_details][address][city]"=Alvin \
  -d "destination_payment_method_data[billing_details][address][state]"=TX \
  -d "destination_payment_method_data[billing_details][address][postal_code]"=77511 \
  -d "destination_payment_method_data[billing_details][address][line1]"="123 Main St." \
  -d "destination_payment_method_data[billing_details][name]"="Jenny Rosen"

If successful, the response returns the newly created OutboundPayment.

{
  "id": "{{OUTBOUND_PAYMENT_ID}}",
  "object": "outbound_payment",
  // The source FinancialAccount. Funds are pulled from this account.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to send. 10.00 USD in this case.
  "amount": 1000,
  "cancelable": true | false,
  "currency": "usd",
  // The destination payment method. Either this or `destination_payment_method_data`

Use POST /v1/treasury/outbound_payments with another financial account defined in the destination_payment_method_data attribute to move money between financial accounts. Both financial accounts must be associated with the same platform, but can be either a financial account attached to a connected account or the platform financial account.

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account={{SOURCE_FINANCIAL_ACCOUNT_ID}} \
  -d amount=2000 \
  -d currency=usd \
  -d statement_descriptor="Test outbound payment to FA" \
  -d "destination_payment_method_data[type]"=financial_account \
  -d "destination_payment_method_data[financial_account]"={{DESTINATION_FINANCIAL_ACCOUNT_ID}}

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

{
  // 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 via the `stripe` network.
  "destination_payment_method_data": {
    "type": "financial_account",

Use GET /v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}} to retrieve details for the OutboundPayment with the associated ID.

curl https://api.stripe.com/v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

If successful, the response returns the OutboundPayment object with the associated ID. Some of the parameters in the response have additional details that are only returned when you add them as values to the expand[] parameter. The fields that you can expand have an “Expandable” comment in the following response example. See Expanding Responses to learn more about expanding object responses.

{
  "id": "{{OUTBOUND_PAYMENT_ID}}",
  "object": "outbound_payment",
  "livemode": true | false,
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  // Will only be set if `destination_payment_method` was used during the creation of
  // the OutboundPayment

Use POST /v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/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.

curl -X POST https://api.stripe.com/v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/cancel \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

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",

Use GET /v1/treasury/outbound_payments to list the OutboundPayments from the financial account with the associated ID. You can filter the list with the standard list parameters or by status or by customer.

{
  // Standard list parameters
  "limit", "starting_after", "ending_before",
  // Filter by status
  "status": "processing" | "canceled" | "failed" | "posted" | "returned",
  // Filter by FinancialAccount (Required)
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // Filter by Customer
  "customer": "{{CUSTOMER_ID}}",
}

The following request retrieves the last five OutboundPayment objects for the financial account attached to the platform and paid to the identified Customer.

curl -G https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d limit=5 \
  -d customer=
{{CUSTOMER_ID}}

The following table describes each status and what the possible transition states are.

To test your integration end-to-end, we recommend using the SetupIntent requests in test mode to create a PaymentMethod, then passing that PaymentMethod into an OutboundPayment creation request using the destination_payment_method parameter.

Stripe also allows test PaymentMethod tokens and numbers to trigger specific functionality:

• By passing in a test PaymentMethod token to destination_payment_method (for ach and us_domestic_wire networks)
  • If you’re passing in a test PaymentMethod token directly into destination_payment_method, you must still pass in a customer ID to the customer parameter. For convenience in this scenario, Stripe allows you to pass in any existing test mode customer. This differs from live mode, which requires the existing PaymentMethod be attached to a Customer and that same customer ID passed into the customer parameter.
• By passing in test routing and account numbers to destination_payment_method_data[us_bank_account] (for ach and us_domestic_wire networks).
• By passing in the ID of an existing test mode financial account owned by an intra-platform account to destination_payment_method_data[financial_account] (for Stripe network).

In all cases, the OutboundPayment response returns the processing status. Stripe triggers webhooks for the relevant state transitions, and fetching the OutboundPayment after creation returns the expected state.

OutboundPayment test helper endpoints

Stripe provides endpoints that make it easier to test OutboundPayments in different states. Use the test endpoints to move an OutboundPayment you create directly to a new state of posted, failed, or returned.

• Use the test post endpoint to move the identified OutboundPayment from processing to posted.

  POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/post

• Use the test fail endpoint to move the identified OutboundPayment from processing to failed.

  POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/fail

• Use the test return endpoint to move the identified OutboundPayment from processing to returned.

  POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/return

These endpoints are particularly useful when testing error scenarios, such as returns, which would otherwise require outside action.

For the return endpoint, include the optional returned_details.code parameter in the body to indicate why the transfer was returned. If not provided, the transfer defaults to the declined return code.

{
  "returned_details": {
    "code": "account_closed" |
          "account_frozen" |
          "bank_account_restricted" |
          "bank_ownership_changed" |
          "could_not_process" |
          "invalid_account_number" |
          "incorrect_account_holder_name" |
          "invalid_currency" |
          "no_account" |
          "declined"
  }
}

In all cases, Stripe triggers webhooks for each relevant state transition, and fetching the OutboundPayment after transition returns the expected state.

Stripe emits the following OutboundPayment events to your webhook endpoint:

• treasury.outbound_payment.created on OutboundPayment creation.
• treasury.outbound_payment.{{new_status}} when an OutboundPayment changes status. Available status value options include:
  • treasury.outbound_payment.posted
  • treasury.outbound_payment.failed
  • treasury.outbound_payment.canceled
  • treasury.outbound_payment.returned
• treasury.outbound_payment.expected_arrival_date_updated when the expected_arrival_date of an OutboundPayment changes.