Creating Payments and Fees

With Connect, you can process charges on behalf of connected users, create subscriptions, and take transaction fees.

Connect allows you to use the full Stripe API on behalf of your connected users. This means, among other things, you can:


Creating payments

There are two ways to create a charge on behalf of a connected account:

  • Create the charge directly on the connected account.
  • Create the charge on the platform’s account, but set a destination parameter identifying the Stripe account that should receive the funds from the payment.

With the first approach, the connected account is responsible for the fees, refunds, and chargebacks. The payment itself will appear as a charge in the connected account.

The latter, new approach provides much more customizability but makes the platform account responsible for the fees, refunds, and chargebacks. The payment appears as a charge in the platform account, along with a transfer from the platform account to the connected account.

Charging directly

Processing a charge directly on a connected account requires authentication, best achieved by providing the platform account’s secret key and the Stripe-Account header:

Note that if you’re creating a charge directly on an account, you’ll only be able use any payment information available on that account: tokens, customers, etc. (When creating tokens, be sure to use the account’s publishable key and not your platform’s publishable key.)

The charge information itself will also only be available on that account—you won’t see it in your platform’s dashboard or reporting.

Charging through the platform

The second way to perform a charge on behalf of a connected account is to create it on your platform’s Stripe account and use the destination parameter (which specifies the connected account ID) in the charge request.

You’ll want to do this if you’d like to keep all of your charge data on one account (e.g. for aggregated reporting), or if you’d like to have greater flexibility over fees and what customers see on their credit card statement. If you’re managing Stripe accounts, we recommend that you create charges directly on your platform.

When you use the destination parameter:

  • The entire amount of the charge will be immediately transferred to the destination account. The ID of the resulting transfer will be returned in the transfer field of the response.
  • The Stripe fee comes out of the charge object on the platform’s account (i.e., you pay the fee).
  • The amount specified by the application_fee parameter (if provided) will be deducted from the total amount and credited to the platform’s account.
  • The charge will be attributed to the destination account for tax reporting.
  • The charge will be settled in the default currency of the destination account. If the platform’s account doesn’t have a bank account in that currency, the application fee will be converted to the platform’s default currency. However, the platform account may accumulate a negative balance in the currency of the destination account due to fees and refunds. Stripe will periodically convert funds from the platform’s default currency to cover any such negative balances.
  • The platform’s account will need to be switched to manual transfers. We don’t currently support using this with the platform account on automatic transfers, but let us know if this is something you’d like us to support in the future.

As you can tell from that list, this approach also creates more objects within Stripe than processing the charge on the connected account directly. The destination account receives a charge object. The platform account will have the charge object and a transfer (the transfer is tied to the destination account’s charge). The platform account will have an application fee object, too, if an application fee was set. Note, as well, that the Stripe fee is paid by the platform account in this case.

This may seem complicated, but such complexity is necessary to handle many edge cases of currency conversion and possible refunds. This structure allows each part of the flow to be refunded independently of others. For example, you can choose to refund the charge to a customer’s credit card with or without reversing the transfer to the connected account, and with or without reversing the application fee you took.


Collecting application fees

With Connect, your platform can take an application fee on charges, subscriptions, and even on transfers.

There are three things to note about application fees, whenever they are requested:

  • The application_fee parameter must be a positive integer (e.g., an amount in cents)
  • The application_fee will be capped at the total transaction amount minus any Stripe fees—no error will be thrown for application fees that are automatically capped
  • No Stripe fees are applied to the application fee

Fees on charges

To charge a fee on top of Stripe’s fees for a one-off charge, all you need to do is pass in the optional application_fee parameter (in cents) when creating the charge.

The resulting charge’s balance transaction will include a detailed fee breakdown:

{
  "object": "balance_transaction",
  "type": "charge",
  "amount": 1000,
  "currency": "usd",
  "fee": 182,
  ...
  "fee_details": [
    {
      "type": "stripe_fee",
      "amount": 59,
      "application": null,
      "currency": "usd"
    },
    {
      "type": "application_fee",
      "amount": 123,
      "application": "ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7",
      "currency": "usd"
    }
  ]
}

Flow of funds

When you specify an application fee on a charge (either by creating the charge, or through recurring billing), the fee amount will be transferred to your (the platform owner’s) Stripe account. If you process a charge directly on a connected account, the charge amount, less the Stripe fees and application fees, will be deposited into the connected user’s account. For example, if a charge $10 was made (as in the example above), $1.23 will be transferred to your account, and $8.18 cents ($10 - $0.59 - $1.23) will be transferred to your connected user’s account.

If you process a charge on the platform account, and use the destination parameter, the charge amount less the application fee will be deposited into the connected user’s account ($8.77, assuming a $1.23 application fee on a $10 charge). The application fee less the Stripe fees (on the charge amount) will be deposited into your account ($0.64, which is $1.23 - $0.59).

Any application fees earned will become available to your Stripe account on the normal 2-day rolling basis, just like funds from regular Stripe charges. Application fees are viewable in the Collected Fees section of the dashboard.

Refunding Fees

When a charge is refunded, the end customer will always be refunded the full amount of the charge. Stripe will never automatically refund the application fee—you must explicitly refund the application fee, or your connected user (the account the charge was created on) will eat the cost of the fee.

You can refund application fees incurred by your application in several ways:


Creating subscriptions

Through Connect, you can create subscriptions on connected user accounts. You can also take an application fee percentage on those subscription payments. Note that both the customer and the plan must be defined on the connected account in order to create the subscription.

Subscriptions do not currently support the destination parameter: they can only be created directly on the connected account.

Fees on subscriptions

When creating or updating a subscription, you can specify an application_fee_percent parameter as an integer between 1 and 100. Each billing period, we’ll take that percentage off the final invoice amount (including any bundled invoice items, discounts, or account balance adjustments) as a fee for your application, on top of any Stripe fees charged.

For example, in a scenario where: the subscription per billing cycle is $100, there’s a $10 invoice item and 50% coupon on the invoice, and the application_fee_percent is 10%, the total application fee taken will be $5.50 (($100 + $10) * 50% * 10%).

Note that application fees on subscriptions must be a percentage, as the amount billed via subscriptions often varies. You cannot set a flat amount for the application fee on a subscription, but can on an invoice (see below).

To create a subscription without an application fee, just omit the application_fee_percent argument.

Prorations and Invoice Items

Invoices created out-of-band of a subscription billing period will not have the application_fee_percent applied to them. This includes proration invoice items that are immediately invoiced—you’ll need to set an application_fee on the invoice directly for the application fee amount you’d like to charge (see below).

If you’re not planning to create any extra invoices, prorations will be automatically bundled into the next billing cycle and will automatically inherit the application_fee_percent set on the updated subscription.

Invoices

If you’d like to charge a flat or dynamic fee, or otherwise any fee that can’t be automatically calculated with application_fee_percent, you can add an application_fee directly on the invoice (usually upon getting an invoice.created webhook, although you can create an invoice for pending invoice items and set an application fee on it).

The application_fee set will override any application fee amount calculated with application_fee_percent, and will be capped if it ends up exceeding the amount of the final charge created.

Permissions

You cannot update or cancel a subscription that was not created by your application. You also can’t add an application_fee to an invoice that was not created by your application or that contains invoice items belonging to another application.


Issuing refunds on charges

Charges created on the platform account can be refunded using the platform account’s secret key:

Charges created on a connected account can be refunded simply by authenticating the platform and identifying the connected account:

When refunding a charge that has a destination value, by default the destination account will keep the funds that were transferred to it (leaving the platform account to cover the negative balance from the refund). To pull back the funds from the connected account to cover the refund, set the the reverse_transfer parameter to true when creating the refund:

When you use the reverse_transfer parameter:

  • A proportional amount of the transfer will be reversed to cover the refund
  • If refund_application_fee parameter is set to true:
    • If the refund results in the entire charge being refunded, all unrefunded application fees will be refunded.
    • Otherwise, a proportional amount of the application fee will be refunded to the Connected account.

Further reading

Read up on the rest of this section to discover what other functionality is available for your users.