How can one retrieve the scheduled payouts from a managed account using STRIPE API?

[Ankit Khatri]

Hi,

So, I am using Connect and doing charge with a destination for managed accounts.

I am able to create charges and transfers to the managed accounts. The transactions on the managed accounts get reflected as payments (IDs starting with py_xxxx). I can list all the transactions of a managed account successfully using stripe.balance.listTransactions() with the managed account auth.

The transfer schedule set for the managed account is 'daily', i.e. they are scheduled to receive payouts daily.

But is there a way to fetch the scheduled payouts as shown in the screenshot below?

[Remi J.]

Hey Ankit,

Based on your screenshot, I'm assuming you want to retrieve what we call upcoming transfers. Those represent transfers that we know we will create at a certain date in the future but that date hasn't happened yet.

We don't yet support retrieving the upcoming transfers in the API though and this feature is limited to the dashboard. You can reproduce this logic yourself though. When you create charges, you get a `balance_transaction` associated with the charge and that Balance Transaction [1] has the property `available_on` which indicates when the funds will be available in the account's balance. For example in the US the funds would take 2 days to go from the charge creation to the balance being available.

If you created a charge today, March 17, the `available_on` of the balance transaction would be set to 1489881600. This is a unix timestamp representing March 19 at 12am UTC. This tells you which day the balance will be released on. 

What I usually recommend here is keep track of all the `available_on` dates on your end for all the charges you create. Based on this, you're able to group all the charges on their `available_on` date for each account to assess when the funds would be transferred to your managed accounts' bank accounts.

I hope this helps!

Remi

[1] https://stripe.com/docs/api#balance_transaction_object

--
You received this message because you are subscribed to the Google Groups "Stripe API Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-discuss+unsubscribe@lists.stripe.com.
To post to this group, send email to api-d...@lists.stripe.com.
Visit this group at https://groups.google.com/a/lists.stripe.com/group/api-discuss/.

[Ankit Khatri]

Hi Remi,

Thanks a lot for such a quick response. We are already showing list of balance  transactions for the managed account to the user. But I know what you say, that we can group it based on available_on.

I have two more questions based on your reply:

1. Once the transfer to the bank account is actually done on the managed account, then I am sure we can fetch it using the stripe.transfers.list API? Right?
2. You said it takes 2 days to go from the charge creation to the balance being available. But on my account, as you can see in the screenshot I sent, its taking 7 days? Any reasons for that? Because of a Test Account?
   Just FYI, while creating the managed account, we used
   transfer_schedule: {
           delay_days:"minimum",
           interval:"daily"
         },
   So, I was actually expecting 2 days but I don't know why it is 7 days? Can you explain?

Thanks.

--

Ankit Khatri

CEO,

CodeMyMobile, Mobile Application Development

B-167, Acharya Vinoba Bhawe Nagar, Vaishali Nagar, 

Jaipur, India

+91-7840868988

Visit us at www.codemymobile.com

**Crafting Apps Intelligently

Skype : CodeMyMobile-USA

Social : LinkedIn | Twitter | Facebook 

Featured on YourStory | CIOReview | SiliconIndia | CrazyEngineers | TakingWings

Latest Release :  Ballzeye - Android Arcade Game - Download Now!

[Remi J.]

Hey Ankit

1. Once the transfer to the bank account is actually done on the managed account, then I am sure we can fetch it using the stripe.transfers.list API? Right?

That's correct! You can make any API request on behalf of your managed accounts. You would use your platform's Secret API key and pass the managed account's id (acct_AACCTT) in the `Stripe-Account` header as documented here [1]. This allows you to retrieve a transfer, create a customer or a plan, etc.

You can also use Connect Webhooks [2] on your platform. This allows you to get the events of all your connected accounts directly any time one is created. Each event will come with a `user_id` key that contains the account id of the managed account the event comes from. You  would listen for `transfer.*` events to know whenever a transfer is created, deposited or when it fails to be able to react accordingly.

1. You said it takes 2 days to go from the charge creation to the balance being available. But on my account, as you can see in the screenshot I sent, its taking 7 days? Any reasons for that? Because of a Test Account?
   Just FYI, while creating the managed account, we used
   transfer_schedule: {
           delay_days:"minimum",
           interval:"daily"
         },
   So, I was actually expecting 2 days but I don't know why it is 7 days? Can you explain?

The first transfer on your account will always take 7 days [3]. So if this is one of your first charges and no transfer has been created yet it's expected. If your platform and the managed account are both in the US, future transfers would take 2 days though. If you're in another country it will depend. For example in France or Spain the transfers always take 7 days after the charge.

Cheers,

Remi

[1] https://stripe.com/docs/connect/authentication#authentication-via-the-stripe-account-header

[2]  https://stripe.com/docs/connect/authentication#webhooks

[3] https://stripe.com/docs/transfers#it-looks-like-my-first-transfer-will-arrive-in-seven-days-but-i-was-expecting-to-receive-funds-sooner

[Ankit Khatri]

Thanks a lot Remi for the detailed reply. Highly Appreciated.

Thanks.

[Charles S]

This solution accounts for balance changes ONLY through charges. From the Stripe docs I see that there are several types of 'balance transactions' such as the following:

adjustment, application_fee, application_fee_refund, charge, payment, payment_failure_refund, payment_refund, refund, transfer, transfer_refund, payout, payout_cancel, payout_failure, or validation

All of the above can result in a balance change on the account. If you choose to gather all the charges and aggregate the sum and group by available_on it wont be accurate if the account also had recent refunds or chargebacks or any other types of adjustments that stripe can make to ones balance.  Be cautious displaying this information to your connect account users because they may be expecting a payout and not receive the same amount.  It would be best if Stripe provided the ability to pass in future timestamps to the 'arrival date' argument when calling on 'https://api.stripe.com/v1/payouts' . 

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

[Roman A]

Could you explain how to calculate the amount and to know when payout is going to happen?

So as I understand, we can keep track of all balance.available_on and group it by date, however I'm assuming it doesn't account for account's payout schedule (daily, weekly, monthly). This can be solved by looking at schedule and estimating when next payout is going to happen (i.e. knowing payouts are set to every monday, can group available balances for monday-sunday). What about weekends and holidays? How does stripe decide when to send out payout if it's a public holiday? For example, if I have daily payouts, and July 4th is Monday - will payout still happen, or rollover and get combined with July 5th amount on Tuesday?

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

[Remi J.]

Hello Roman,

Unfortunately, this is not something that is possible today. You can't replicate the exact same logic that we have on our end for those calculations for the reasons that you raised (week ends, public holidays per country, etc.). The best you can do is a best guess based on the account's payout schedule, its country and the relevant bank holidays associated with that country. That is the only way to handle this and you would end up mimicking what we do on our end for each country.

In the future, we hope to give access to an upcoming payout endpoint/API that would let you surface the information to your users in a more reliable way. This is not something we plan to ship in the short/medium term though and your best bet is to try to come as close from it as you can.

Sorry I don't have a better answer for this.

Best,

Remi

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

[zur...@rollkall.com]

Hello, so we are trying to do something similar. My question here is, if I create a webhook to listen to the payout.paid event, will I get the user connect account id that that payout even happened on?

Right now we are testing the webhook and I am not seeing that on the body of the payout. Only the destination bank account.

[Remi J.]

Hello,

There are two types of webhook endpoints: the Account webhook [1] and the Connect webhook [2]. The former receives all events from your own Stripe account such as your own Payouts or charges. The latter is what you configure as a platform to get events from all of your connected accounts.

When we send an event from your connected account, the event payload will have the `account` property set to the id of the account that the event is coming from. This allows you to identify the account associated with that event and react accordingly.

Best,

Remi

[1] https://stripe.com/docs/webhooks

[2] https://stripe.com/docs/connect/webhooks

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

[zur...@rollkall.com]

Oh, excellent. Thats what we were missing. The account is on the top level stripe event object, not on the payout object. Ok, thank you.