Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Start an integration
Products
Global Payouts
Capital
Issuing cards
Treasury
    Overview
    How Treasury works
    Eligibility requirements
    Get Started
    Get started with API access
    Onboarding users
    Managing fraud
    Marketing and compliance guidelines
    Sample integrations
    Use Treasury to set up financial accounts and cards
    Use Treasury to move money
    Issuing and Treasury sample application
    Stripe Issuing and Treasury
    Webhooks for Stripe Issuing and Stripe Treasury
    Working with Stripe Issuing cards
    Account management
    Stripe Treasury accounts structure
    Working with connected accounts
    Working with financial accounts
    Financial account features
    Platform financial accounts
    Working with balances and transactions
    Moving money
    Payouts and top-ups from Stripe Payments
    Working with SetupIntents, PaymentMethods, and BankAccounts
      ACH Notification of Change handling
      ACH Standard Entry Class handling
    Moving money into financial accounts
    Moving money out of financial accounts
    Money movement timelines
    Bank partners
    Fifth Third Bank overview
    Get started with Fifth Third Bank
Manage money
HomeMoney managementTreasury

Working with SetupIntents, PaymentMethods, and BankAccounts

Set up money movements in Treasury.

Copy page

You can use PaymentMethod objects to save account credentials for a US-based bank account for future use. After creating the PaymentMethod, you can use the same object repeatedly to move funds into and out of a financial account. Depending on your use case, you can attach the PaymentMethod to either a Customer object or the Stripe account.

  • Attach the PaymentMethod to a Customer object if you intend to use the payment method for an outbound payment to a third party.
  • Attach the PaymentMethod to a connected account or platform account if you intend to use the payment method for an inbound transfer or outbound transfer between an external account that belongs to the same business as the Stripe account.

Note

The Customer object defines a third-party entity that represents the owner of an external bank account.

If you previously collected customer payment details with Stripe using the BankAccounts object, you can substitute the BankAccount for a PaymentMethod in those requests. For InboundTransfers, the BankAccount status value in this case must be verified. We recommend using PaymentMethods where possible to get the full suite of features.

In some cases, banks on the receiving end of ACH money movements notify Stripe that account information (such as account number or routing number) has changed. If we receive such a notification for an account associated with a PaymentMethod or BankAccount object, we automatically update the object. See the ACH Notification of Change handling guide for more information.

Create a SetupIntent to save us_bank_account details

SetupIntents enable you to set up a payment method to use with money movement endpoints of the Stripe API. Use SetupIntents to save customer or account credentials as a payment method and optimize them for the objects you intend to use it with. For example, when setting up a US bank account, it’s necessary to verify the bank account if you intend to debit that external account with an inbound transfer. Stripe updates the SetupIntent object throughout the setup process.

The following example demonstrates using a SetupIntent with a bank account that allows for bidirectional fund transfers. For complete details on how to set up a payment method for creating payments and bank account verification, see the Save details for future payments with ACH Direct Debit guide. When setting up payment methods for managing financial account funds with SetupIntents, the following fields are the most relevant:

  • flow_directions: this array defines the directionality of the flows for a payment method. Its possible values are inbound and outbound, denoting whether the payment method can move funds into, out of, or both into and out of a financial account. You can also configure an existing payment method to become bidirectional.
  • attach_to_self: a Boolean flag to indicate whether you want to attach this payment method to the in-context Account object. Set this value to true to create an account-attached payment method for managing this account’s own money movement flows such as inbound transfers and outbound transfers.
  • customer: ID of the Customer object the payment method is attached to on successful setup. You can use Customer-attached payment methods with outbound payments to send money to third parties and customers. You can also use them with Stripe Payments PaymentIntents to receive money. You must set the attach_to_self attribute to false or leave it blank when creating a customer-attached payment method.

Permissions

To use a payment method for ‘inbound’ flow directions (such as InboundTransfers), you need permission from the account holder. Creating this agreement (Mandate object) up front and associating it with the payment method allows you to charge the payment method later.

Add terms to your website or app that state how you plan to debit funds from external accounts, and let connected accounts opt in. At a minimum, make sure that your terms cover the following:

  • Connected account permission for you to initiate a debit or a series of debits on their behalf
  • The anticipated frequency of debits (one-time or recurring)
  • How the debit amount is determined

While you need a mandate to debit an external bank account in the US with inbound transfers, you don’t need it to send money to a bank account with outbound transfers or outbound payments.

Creating a SetupIntent

To create a SetupIntent, you must either use an existing payment method with the payment_method parameter, or provide new credentials using the inline payment_method_data parameter.

Use POST /v1/setup_intents to create a SetupIntent.

Command Line
cURL
curl https://api.stripe.com/v1/setup_intents \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -H "Stripe-Account:
{{CONNECTED_ACCOUNT_ID}}
"
\ -d payment_method=
{{PAYMENT_METHOD_ID}}

If successful, the response returns the newly created SetupIntent object.

JSON (commented)
{ // ID of the Customer to attach the resulting PaymentMethod to "customer": "{{CUSTOMER_ID}}", "attach_to_self": false, // Configure what direction of funds flows this PaymentMethod will support. "flow_directions": ["inbound", "outbound"], // US Bank Account credentials "payment_method_types": ["us_bank_account"], "payment_method_data": { "type": "us_bank_account",

The SetupIntent has one of the following statuses:

STATUSDESCRIPTIONNEXT STEPS
succeededThe bank account has been instantly verified or verification isn’t necessary.No action needed.
requires_actionFurther action needed to complete bank account verification.See next_action for further setup steps.

After successfully confirming the SetupIntent, Stripe sends an email confirmation of the mandate and collected bank account details to your connected account. The default email references Stripe Payments, so if you use Stripe Treasury without Stripe Payments, you might want to turn off Stripe emails and send custom messages instead.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc