#raimund_payout-balance
gray iceBOT
👋 Welcome to your new thread!
⏲️ We'll be here soon! Typically we respond in a few minutes, but sometimes we might take a bit longer if the server is busy or if you have a particularly tricky question.
⏱️ We close idle threads, which makes them read-only. Once a thread is closed it won't be reopened, but you can always start a new thread if you have another question.
🔗 This thread will always be available, even after it's closed. You can find it again using Discord's search, or you can save this link: https://discord.com/channels/841573134531821608/1278747488886722712
📝 Have more to share? Add more details, code, screenshots, videos, etc. below.
compact saddle
raimund_payout-balance
@severe kraken when you get an API error you can see detailed information about why the error was raised. I recommend carefully reading https://docs.stripe.com/error-handling and adapting your code to cleanly catch the error and log all the details.
The error is quite descriptive if you look at it and it says
{
error: {
code: "balance_insufficient",
doc_url: "https://stripe.com/docs/error-codes/balance-insufficient",
message: "You have insufficient funds in your Stripe account for this transfer. Your card balance is too low. You can use the /v1/balance endpoint to view your Stripe balance (for more details, see stripe.com/docs/api#balance).",```So this connected account doesn't have enough balance for the Payout to work. My guess is that you didn't realize funds aren't available immediately and that you have to wait to be able to create a Payout
severe kraken
Yeah, I see the error. I'm just not sure why this has happened. We confirmed that our idea of the balance is the same that I can see inside Stripe's UI directly.
compact saddle
We confirmed that our idea of the balance is the same that I can see inside Stripe's UI directly.
what does that mean? What's your idea? Where do you see the balance?
compact saddle
I think you are mixing up your ids or views here. What account did you create the Payout on, like what's the id?
severe kraken
You mean our main account ID or the recipient?
compact saddle
You are a platform. You are trying to create a Payout for a connected account. I am asking what is the id of that connected account that you are using. Because that account does not have the balance you show in this screenshot.
I think you are either looking at the wrong connected account, or worse you are mixing things up and looking at your own platform's account balance
severe kraken
acct_1PF0AkBScBEJeeSd
compact saddle
yeah okay, you're mixing up your ids here. You created a Payout on a completely different connected account acct_1O7oFqPko5x7sRRh
severe kraken
Sorry, yes, the requests don't match this account, but we're facing the same issues there. That's our test account.
compact saddle
sure but you gave me 2 requests and they both are on a completely different account that does not have a balance
severe kraken
Not anymore. Let me explain the long story:
- The account ID I gave you is the one of the user who reported this initially. You're right, these aren't the requests.
- The requests are from our test account.
- Our DB says a balance of $1. The Stripe UI said the same thing when we sent the requests.
- Only to check what happens I initiated a payout inside the Stripe UI, and that went through.
So that explains why the balance is 0 now, but I assure you it wasn't.
For example, one that failed for the account in question was req_zWGkXdvLBzicay
compact saddle
Okay, what is their balance in the API? Can you call the Retrieve Balance API for them (with the Stripe-Account header: https://stripe.com/docs/connect/authentication#stripe-account-header)` and share
- your exact code.
- the exact raw JSON you got back in the response
severe kraken
Setting that up may take a while, please don't close this thread yet.
compact saddle
Sure!
severe kraken
So I just ran this quickly via your Shell and received this:
{
"object":
"balance",
"available": [
"0": {
"amount":
38200,
"currency":
"usd",
"source_types": {
"card":
38200,
},
},
],
"instant_available": [
"0": {
"amount":
38200,
"currency":
"usd",
"source_types": {
"card":
38200,
},
},
],
"livemode":
true,
"pending": [
"0": {
"amount":
0,
"currency":
"usd",
"source_types": {
"card":
0,
},
},
],
"refund_and_dispute_prefunding": [
"0": {
"amount":
0,
"currency":
"usd",
},
],
}
compact saddle
did you use Workbench for this instead of writing real code end to end?
But note how that one has $382 in their card balance but for some reason your code is trying to create a Payout that pulls from the bank_account balance which is at $0.
Your code explicitly passed source_type: "bank_account" as a parameter
severe kraken
What would happen if we dropped the source_type parameter completely?
compact saddle
it'd only pull from the card balance.
If you are an old platform (2+ years old) and accept ACH Debit payments via our older integration (btok_123 and ba_123) then you have to handle both source_type and keep track of the split balance explicitly and then create a Payout from the right sub-balance
severe kraken
OK, so the bigger context of all this is:
We want to enable our payment recipients to choose which account to send their payouts to. Are you telling me that we can't do that?
compact saddle
No, I never said that at any point. I'm happy to explain anything but I don't know what you know and don't know exactly here unfortunately.
You came saying "why is the request failing" and I'm explaining that you either don't have enough balance (the first account was at $0 available) or now that you are using the wrong source_type (that account has funds in their card balance but you asked to pull from their bank account balance).
This has nothing to do with the destination for the funds which would be the bank account outside of Stripe, at their bank, where you are sending their money
This is definitely subtle but I should get you squared away quickly once I get which part you're confused about
severe kraken
Sorry about that, I'm probably goign to ask a few more dumb questions.
We've been trying to use connected accounts for payouts, but that's probably the wrong approach?
compact saddle
Depends what that means. Are those different businesses that you're helping accept payments for?
severe kraken
Different from ourselves? Yes.
compact saddle
Then that is the right way. It's exactly what Stripe Connect was built for.
severe kraken
But source_type is probably the wrong mechanism? Do we need to use externalAccount instead?
compact saddle
not really. Sorry did you actively write this part of the code? Or are you debugging someone else's code?
severe kraken
Partially.
compact saddle
Okay. Do you accept ACH Debit payments?
severe kraken
Yes
compact saddle
Okay, do you know if you are using our legacy integration, the one that splits the funds between the card and bank_account in source_type? It's fine if you don't know, but it is crucial to know and understand what you are doing
severe kraken
Let's assume I don't know, what would be the easiest way to find out?
compact saddle
it's not easy, that's why I'm asking if you know
severe kraken
What I can tell you is that code that used to do this function honoured the split balances by requesting the different balances before issuing the payout request.
Notch has been interacting with Stripe since 2021.
Does this help?
compact saddle
it helps a bit
that code that used to do this function honoured the split balances by requesting the different balances before issuing the payout
then that's your issue. You clearly didn't do that in this case right?
severe kraken
Correct, yes. I had some questions about this in previous weeks and received answers that led me to believe we could this in the way that we're intending, but apparently we missed something.
compact saddle
yeah
And I did look and I confirmed that you do use our Legacy ACH Debit integration via our old /v1/charges API. So this is why you have the balance split like this
What your team could do is spend time upgrading to our newer integration through PaymentIntent because that one does not split the balances and would make your life much easier in the future
In the meantime: you need to fix your Payout creation logic by first looking at their balance and the exact split between card and bank_account
severe kraken
OK, that makes some sense, thanks.
compact saddle
Sure thing. That split balance has been the bane of my existence for many years. It's so confusing and subtle and almost no one understands it
I'm really glad we finally fixed it 2 years ago with our newer integration though!
severe kraken
I'm starting to see why I found some of the API doc information contradicting. I saw this thing about the separate balances in the previous code and also somewhere in the API docs, but we've been told that what we're trying to do is possible. Now I see where the confusion stems from : It IS possible, but we need to start working somewhere else first.
compact saddle
yeahhhh and the problem is that this source_type is obscure in the first place and so even on my team, people who joined less than say 3 years ago likely don't know about it 😦
severe kraken
So just to conclude this: I'll roll back our changes for now, but what is the correct way forward for us?
You mentioned something about the way we're setting up the PaymentIntents?
compact saddle
Right now you are accepting ACH Debit payments via our legacy API using the Create Charge API. It's different from how you accept card payments since I do see you use PaymentIntents too elsewhere.
So the next step would be to migrate your integration for ACH Debit payment to our newer integration on PaymentIntent. See https://docs.stripe.com/payments/ach-debit/migrating-from-charges as a good start
severe kraken
And once we've done that, we ask everyone to clear out their existing balances and then how do we set up the "new" payout correctly?
compact saddle
yep exactly!
severe kraken
Sorry, how do we set up the "new" payout correctly? Instead of adding that source_type, we do what?
compact saddle
At that point, all the funds will always be in the card balance so you don't need to pass source_type at all in that case because card is the default
severe kraken
Sorry, now you lost me again.
Our mental model is this:
- We have a small number of clients - we refer to them as "assignors" who pay big amounts into our platform.
- At the other end are the "officials" who receive portions of that via Payouts.
- In between, we transfer funds from our balance to the officials' balance and retaina small fee.
- What we want to do is enable the officials to select the account the payout actually ends up in. This can be a card or a bank account.
How does a payout request need to look for that scenario?
(The actual background of all this are the fees for instant payouts which we're absorbing at the moment, but want to pass on to the officials.)
compact saddle
yeah I can see I lost you but I don't get why you come back again to "where to send the money". That part has not changed
the source_type has nothing to do with whether the Payout is sending funds to their bank account or debit card. This is not related at all.
It's only about where funds came from when someone paid you money (either from their card or bank account)
severe kraken
Got you.
So instead of the source_tyoe we use the externalAccount object?
Sorry for keeping you on this so long, but this is the best support chat experience I've had in a long time.
compact saddle
So funds will only come in your "card balance" internally. So you remove source_type entirely as a parameter because you won't need it anymore.
Separately, where to send the funds has not changed. You (as the developer) already control this today. When you are creating a Payout, your code is explicitly passing destination as a parameter which is the id of the "external account" attached to that connected account that you want to send funds to. Today this can either be a Card id card_1234 usually for instant Payouts, or a BankAccount id ba_12345
today you already do this properly and pass destination: 'card_12345' or destination: 'ba_ABCDE' and that is not changing at all.
And no worries on the time. It's my job to help here and I love it. Fun fact: this discussion was fun so I asked someone on my team to leave me their shift to keep having it :p
I'll run in ~15 since I have meetings but someone else on my team will take over Discord and answer questions (including yours if you have more)
severe kraken
So all I need to do is drop that source_type, and we're probably fine. I think I've got it now. Thanks.
compact saddle
yeah but remember: you can only drop that source_type once every connected account has only a card balance
until then, you have to check the sub-balance card and bank_account and pass the right one
severe kraken
Yeah, I'll roll back for now. Thanks, I think that's all.