Adding funds to your platform balance with payment method

Overview

We provide platforms with several money movement APIs to manage users’ funds. To fund a merchant balance, platforms can create a top-up to pull funds from a user’s external bank account by providing a payment method.

This guide describes how to create a payment method with an external bank account and add funds to the merchant balance with the payment method.

SetupIntents and PaymentMethods

A PaymentMethod is a way to save account credentials for a US-based bank account for future use. After setup succeeds, you can use the same PaymentMethod multiple times to move funds into the merchant balance.

SetupIntents are a state machine that allow you to set up a PaymentMethod to use with these money movement APIs. Use the SetupIntents API to save the credentials as a PaymentMethod and optimize them for the API you intend to use it with. For example, when setting up a US bank account, it might be necessary to verify the bank account before debiting it. We update the SetupIntent object throughout the process.

Create a SetupIntent to save US bank account details

A SetupIntent is an object that represents your intent to set up a payment method for usage with a money movement API endpoint. The SetupIntent tracks the steps of this set up process.

See Setting up a us_bank_account PaymentMethod for information on how to set up a PaymentMethod for creating Payments and verifying the bank account. The process for setting up PaymentMethods is similar to the money movement APIs described in this guide. When setting up PaymentMethods for top-ups with SetupIntents, the following fields are the most relevant:

• flow_directions : this array indicates the directions of money movement. Top-ups require inbound included in this array.
• attach_to_self : a boolean flag to indicate whether you want to attach this PaymentMethod to the in-context Stripe account. Set this to true to create an account-attached PaymentMethod for managing this Stripe account’s own money movement flows.
• mandate : an object with a customer _ acceptance field having the type offline .

Depending on the flow_directions you specify, you might require permission from the user to save the PaymentMethod. Creating this agreement (or mandate) up front allows you to charge the PaymentMethod later.

Add terms to your website or app that state how you plan to process payments and let users opt in. At a minimum, make sure that your terms cover the following:

• The user’s permission for you to initiate a payment or a series of payments on their behalf
• The anticipated frequency of payments (one-time or recurring)
• How the payment amount is determined

You need the user’s permission for debiting an external US bank account with top-ups. You don’t need permission for sending money to a bank account.

Before creating a SetupIntent, enable US bank account as a payment method in your Dashboard.

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

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Set up your default bank account as a PaymentMethod

To set up your default bank account as a valid PaymentMethod, pass it to the SetupIntent as follows:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

If successful, we return a SetupIntent object with one of the following possible statuses:

After successfully confirming the SetupIntent, an email confirmation of the mandate and collected bank account details must be sent to your customer. We send these by default, but you can send custom notifications instead.

Top-ups

Top-ups represent pull-based transfers from an external account you own into your merchant balance. You can create a top-up to move funds into your merchant balance by debiting your external US bank account.

Create a top-up

When you add funds through the API, a top-up object is created.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

When you transfer funds, a statement descriptor appears on your banking statement for the transaction. The default statement descriptor is “top-up.” You can customize the statement descriptor and internal description for the top-up.

Testing top-ups

To test your integration end-to-end, we recommend using the SetupIntents API in a sandbox environment to create a PaymentMethod, then passing that PaymentMethod into a top-up creation request. Valid PaymentMethods result in succeeded top-ups, while invalid PaymentMethods (for example, PaymentMethods of unsupported types, or PaymentMethods that aren’t set up for inbound flows) display the same errors in live mode.

We also provide a set of test bank account numbers that you can pass into the payment method setup. Use these test bank account numbers to test top-ups. You can only use them with test secret keys.