connect API payouts vs transfers

[Igor Shmukler]

Hello,

I am reviewing the documentation. See that there are several ways of
funding connected accounts, including:

const transfer = await stripe.transfers.create({
amount: 7000,
currency: 'usd',
destination: '{{CONNECTED_STRIPE_ACCOUNT_ID}}',
transfer_group: '{ORDER10}',
});

and there is also:

const payout = await stripe.payouts.create({
amount: 7000,
currency: 'usd',
},
{
stripeAccount: '{{CONNECTED_STRIPE_ACCOUNT_ID}}',
});

Is there any practical difference as to which APIs are utilized
[except the correlation with a transfer_group]?

I use payment intents to capture funds, as below:

const paymentIntent = await stripe.paymentIntents.create({
payment_method_types: ['card'],
amount: parseInt(total * 100),
currency: 'usd',
// commission charged by the platform USD * % is Cents
// therefore: (total) * (fee percentage) = (cents)
// platform fee in percent plus 2.9% + 30 cents charged by Stripe Connect
application_fee_amount: parseInt(total * (platformFee + 2.9) + 30),
transfer_data: {
destination: `${accountId}`
},
capture_method: 'manual',
confirm: false
});

Since capture is manual, the funds are not being paid out
automatically. I have a scheduled job calculating total due amounts
and initiating payouts. Which API should be used for this?

[Remi J.]

Hey Igor,

In our API, a Transfer represents money moving between your own Stripe account's balance (the platform's) and the connected account's balance. The funds move between the accounts but stay within Stripe. On the other hand, a Payout represents money moving from a Stripe account's balance to their own bank account outside of Stripe (or debit card in some cases). They are two completely separate APIs with a different logic and behaviour.

In your example, you are creating a PaymentIntent. That PaymentIntent has `transfer_data[destination]: 'acct_123'` and `application_fee_amount` set. This is called a Destination Charge. What this means is that your customer is going to pay $10, you're going to transfer those $10 to the connected account's balance but also take back your own share as an ApplicationFee (say $1) and you as the platform also pay our fee (Stripe's). In this world, the customer pays $10, you give $9 to the connected account ($10 amount minus your $1 application fee) and you net out $0.41 (our fee is $0.59 in this case).

Now you also mentioned that you are using manual capture. So, when the Customer pays, the funds are only "authorized" but they haven't moved yet. At some point you will capture the payment which will start our process of settlement. At that point, the Transfer for $10 to the connected account will be created and the ApplicationFee moving back $1 to your account will too. All those objects will have what we call a BalanceTransaction associated with it. This object represents the money movement in your balance. It has a property called `available_on` that will indicate when the funds will be available in that account's balance. In the US, it takes 2 days for a card payment to be available after its capture and until it's available the funds are considered pending and are in the pending balance.

What this means is that on Monday you create the payment without capturing. On Tuesday you capture which moves all the money in both accounts. At this point, your account will see a $0.41 positive balance as your share. The connected account will see a positive balance of $9. But the funds aren't available yet, they stay in the pending balance until Thursday when they would be made available.

By default, Stripe accounts are on automatic Payouts. What this means is that daily, we will aggregate all the funds that are settling that day and if the amount is positive we will create a Payout to send the money to the bank account (or debit card) associated with that Stripe account. Unless you explicitly switch your connected account's payout schedule to manual (which most businesses don't) you really don't need to do anything else and the funds will be paid out daily whenever they become available. If your connected account has sales every day they'd simply get a new Payout each day.

This is a lot to digest though in one email. Our docs cover a lot of this in details and I'd recommend going through some of the following links:

* https://stripe.com/docs/payouts

* https://stripe.com/docs/connect/bank-debit-card-payouts

* https://stripe.com/docs/connect/manage-payout-schedule

If you have any follow up questions, I recommend talking directly with our support team and they can help you understand this further and tailored to your business model and specific examples you could share. You can contact them here: https://support.stripe.com/contact

Hope this helps!

Best,

Remi 

--
To unsubscribe from this group and stop receiving emails from it, send an email to api-discuss...@lists.stripe.com.

[Igor Shmukler]

Hello Remi,

Thank you for the detailed answer.

I thought that the below would hold capture funds and hold them until
I schedule a payout:

const paymentIntent = await stripe.paymentIntents.create({
payment_method_types: ['card'],

// amount is in cents, so $1.00 is 100, while internally it is in
decimal numbers

amount: parseInt(total * 100),
currency: 'usd',
// commission charged by the platform USD * % is Cents
// therefore: (total) * (fee percentage) = (cents)
// platform fee in percent plus 2.9% + 30 cents charged by Stripe Connect
application_fee_amount: parseInt(total * (platformFee + 2.9) + 30),
transfer_data: {
destination: `${accountId}`
},
capture_method: 'manual',
confirm: false
});

Plus, when I create connected accounts, the payout interval is set to
manual, as below:

const account = await stripe.accounts.create({
country: 'US',
type: 'express',
capabilities: {
card_payments: {
requested: true
},
transfers: {
requested: true
}
},
settings: {
payouts: {
schedule: {
interval: 'manual'
}
}
}
});

In my case, there will be no automated payouts, unless I explicitly
schedule them, right?

Thank you

[Remi J.]

Since you do switch your connected accounts to manual Payouts then we won't send the money automatically. You will always have to explicitly create a Payout to move money from their balance to their bank account. This works but is a lot more work to handle and build so we usually discourage it unless you need to hold funds for some reason. 

As for the capture, that's correct, no money is moving in that case until you manually capture. But you can only hold funds on a card for 7 days before they are automatically refunded. This is covered in details in this doc. So you can't use that flow to hold funds for multiple weeks or months.

Hope this clarifies it all but our support team would be best if you have follow up questions!

Best,

Remi