Compare SaaS platform configurations for Accounts v1 and Accounts v2
Learn how a SaaS platform charges its connected accounts with Stripe Billing using Accounts v2.
SaaS (Software as a Service) platforms using Connect often charge subscription fees for providing their platform services. We recommend using Accounts v2 for all new platforms to take advantage of new features, such as the ability for a single connected account to pay for a subscription (as a Customer) and operate on the platform (as an Account). If you are already familiar with Accounts v1, this document will help you get started with Accounts v2 by outlining the differences.
The Accounts v2 API
In API v2, Account objects can have multiple configurations. Each configuration represents a different type of business relationship and enables different Stripe products. By assigning multiple configurations to an Account, a SaaS platform can enable both Connect and Billing for it without also having to create a Customer.
The Accounts v2 API provides:
- Unified representation: A single Account object can represent multiple relationships between connected accounts and your platform.
- Flexible configurations: Enable or change Stripe products and capabilities by changing the configurations assigned to an Account .
- Centralised identity data: The Account object stores all of a connected account’s identity data. When you add a configuration to an existing Account , you don’t have to collect requirements that they already provided.
When looking at Stripe documentation, be aware of the structural differences between an Account in API v2 and an Account in API v1. For example:
- In Accounts v2, some properties are part of an Account ’s configuration or identity properties.
- Accounts in API v2 associate functionality such as card _ payments and stripe _ balance. stripe _ transfers with a configuration type.
- In API v2, each requirement has its own status properties. In API v1, an Account includes arrays for each requirement status, and requirements appear in one or more of those arrays, according to their status.
The following table illustrates how some Accounts v1 properties map to Accounts v2 properties.
| Accounts v1 property | Accounts v2 property |
|---|---|
| business_profile.url | defaults.profile.business_url |
| business_profile.support_url | configuration.merchant.support.url |
| business_profile.product_description | defaults.profile.product_description |
| Each requirement appears in one or more arrays, according to its status. requirements.currently_due requirements.eventually_due requirements.past_due | All requirements are in a single array. To check a requirement’s status, look at its minimum_deadline.status. Individual requirement status: requirements.entries.minimum_deadline.status Earliest due status: requirements.summary.minimum_deadline.status |
To compare the required verification information between Accounts v1 and v2 for a specific configuration, use the Required verification information page, which lets you compare requirements side by side.
Using Connect and Billing in API v1 with Accounts and Customers
In API v1, Account objects support only Connect features. To charge a connected account using a subscription, a platform must create a Customer object representing the same connected account. Accounts v1 and Customers v1 have no explicit relationship, so the platform must manage those objects separately and maintain a map of Account IDs to Customer IDs.
SaaS platform relationships with Accounts and Customers in API v1
Using Connect and Billing in API v2 with Accounts
With Accounts v2, a connected account that collects payments and pays you a subscription fee doesn’t require both an Account object and a Customer object. Instead, you represent it by assigning the applicable configurations to the Account.
To enable a connected account to collect payments from customers, assign the Merchant configuration to the corresponding Account.
Platform and Account with Merchant configuration
To enable the platform to collect payments, including subscription payments, from the connected account, add the Customer configuration to the Account.
Platform and Account with Merchant and Customer configurations
Note
You can collect application fees from an Account with the Merchant configuration. Assigning the Customer configuration to it doesn’t affect that ability.
Accounts API v2 limitations
You must use Accounts v1 in the following cases:
- Using OAuth to authenticate connected accounts
- Signing connected accounts to a recipient service agreement
- To request or manage the following capabilities:
- treasury
- card _ issuing _ *
- deprecated capabilities such as legacy _ payments
- deprecated payment methods
- certain payment methods in public or private preview
Cross-border payouts
Use Global payouts to send cross-border payouts.