Pay with Stripe balancePublic preview

As a Connect platform, you can create a payment method linked to a connected account’s available Stripe balance. This allows you to collect subscription payments directly from a connected account’s available balance, instead of through external payment methods such as cards.

Integrate payments from Stripe balances

This payment method is only available as part of a preview release with Accounts V2.

Eligibility

Stripe balance payments are subject to the following conditions:

• You can only configure this payment method for an active connected account that’s controlled by your platform and that has the card_payments capability active.
• You can only use this payment method for debiting subscription payments from connected accounts where your platform provides payments functionality through Connect, not for any other goods or services.
• Paying from a Stripe balance is not available when using Dynamic Payment Methods. You must explicitly specify paying from a Stripe balance as a payment method when creating a subscription payment.

Required approval from your connected accounts

You must obtain approvals from your connected accounts before collecting payments from their Stripe balances. We recommend using the following language to inform your connected accounts, and that you provide an option to opt out of paying from their Stripe balance:

Timing and availability of funds

Payments made from a Stripe balance are confirmed immediately. Stripe balance payments from connected accounts in the same country as your platform become available in your Stripe balance with same-day settlement (T+0). Cross-border payments from connected accounts in a different country become available in your Stripe balance with next-day settlement (T+1).

Cross-border payments

You can create Stripe balance payments in a currency other than your platform’s default currency, as long as the connected account’s Stripe account includes that currency. Stripe automatically converts the funds to your platform account’s default currency.

Refunds

You can partially or fully refund any successful Stripe balance payment in the same way you refund card payments.

Transaction failures

Payment from a connected account’s Stripe balance requires sufficient available funds in the specified presentment currency. Otherwise, the PaymentIntent fails with an insufficient_funds decline code. The payment fails even if the account has sufficient funds in a different currency.

We recommend configuring your integration to manage balance-related payment failures.

Avoid balance payment failures

Because payments from a connected account’s Stripe balance rely on its available funds, you can avoid payment failures by taking steps to maximize your connected accounts’ balances.

Tailor connected account payout schedules

Coordinate your payout schedules with your subscription billing cycles. For example, if you charge subscription fees on the first day of each month, and schedule weekly payouts on Mondays, then months with more Mondays have more payouts. Those months have lower available balances than months with fewer payouts, making payment failures more likely.

Another way to avoid payment failures due to payouts is to change to manual payouts before a subscription payment. At a set time before each subscription payment, if a connected account has sufficient available funds, switch it to manual payouts so the subscription payment gets paid before the automatic payout clears the account. After the subscription payment, resume automatic payouts.

Set a minimum balance on connected accounts

You can prevent automatic payouts from reducing a connected account’s available balance below a certain amount by defining a minimum balance for that account.

1. Find the account in your Dashboard.
2. From the account’s overflow menu (), select View Dashboard as….
3. Click the gear icon and select Settings.
4. Under Account Settings, click Business.
5. Select the External payout accounts and scheduling tab.
6. Turn on Keep a minimum amount in your payments balance and enter an amount.

You must manually set the minimum balance for each connected account.

Handle balance payment failures

Set up webhooks and event destinations to receive notifications about subscription payments. Identify payment failures by listening for the invoice.payment_failed event. When a payment fails:

• The PaymentIntent status changes to requires_action.
• The Subscription status remains incomplete for the current invoice.
• The Subscription continues to generate invoices, which remain in draft status.

If a payment from a Stripe balance fails due to insufficient available funds, you can retry it by following these steps:

1. Set the connected account’s payout schedule interval to manual.
2. Listen for the next payment that comes into the connected account, then check the account’s available balance.
3. If the available balance is equal to or greater than the subscription fee, set the unpaid invoice’s payment method to stripe_balance and retry it. Otherwise, continue listening for payments until the available balance is enough to pay the invoice.
4. If the payment succeeds, restore the connected account’s normal payout schedule.

Instead of retrying a failed payment from a Stripe balance, you can try using a different payment method by specifying it directly on the invoice. You can also implement a flow that allows connected accounts to update their own subscription payment methods.

Reporting and payment tracking

Payments made using a connected account’s Stripe balance generate transaction data reflecting the payment details on both the platform and the connected account.

On the platform, the payment creates a Charge and a BalanceTransaction with positive amounts. The BalanceTransaction has the following values:

• reporting_category: charge
• source: Charge object ID
• type: payment

On the connected account, the payment creates only a BalanceTransaction, with a negative amount and the following values:

• description: "Stripe balance payment - " + description from the PaymentIntent
• reporting_category: stripe_balance_payment_debit
• source: null
• type:
  • For payments: stripe_balance_payment_debit
  • For refunds: stripe_balance_payment_debit_reversal