Destination Parameter and Transfer Confusion

[roy whitburg rwhitburg]

Hello. I'm testing the API by creating a Charge Object with a destination parameter which has assigned to it a Stand-alone account that is Connected to my platform. The following language from the Stripe docs seems to contradict itself regarding "manual transfers." The first statement says we need to switch to manual transfers for destination params to work. Then next statement says, we "almost always" want to do something "rather than manually" transferring. I'm confused. I thought after getting the Charge response back the transaction was "done." We're free to ship. But is the charge still just pending? Is there an additional manual step I must take (if so, how?) or something is there something automated that I'm waiting for before the transaction can be considered complete?

From, https://stripe.com/docs/connect/payments-fees#charging-through-the-platform

"When you use the destination parameter:   ....The platform’s account will need to be switched to manual transfers."

From, https://stripe.com/docs/connect/special-case-transfers

"you’ll almost always want to use the destination field on the charge (which results in a transfer) rather than manually creating a separate transfer"

Thanks.

[Remi J.]

Hey Roy,

This is covered in the documentation for the `destination` parameter [1] where we say:

"The platform’s account will need to be switched to manual transfers. We don’t currently support using this charging approach with the platform account on automatic transfers."

What this means is that you need to head to the transfers settings [2] for your *platform* account and click on "Switch to manual transfers" for this flow to work properly from now on. What that entails is that we won't send automatic transfers to your bank account anymore on your platform. The balance you get from application fees [3] will get built up over time and accumulate in your account. You'll need to send manual transfers to your own bank account through the API [4] or directly in the dashboard when you want those funds to get transferred to you. This will *not* impact the connected accounts and they can stay on automatic transfers if they want to.

The reasoning behind this limitation is that every platform will, at some point, have to create a manual transfer from their available balance. This happens to cover a refund, a one-time promotion, a chargeback that got reversed, etc. The only way to do this is to have some funds in your available balance which is one of the main reasons we require you to switch to manual transfers. We usually recommend to keep some funds in your account to cover those cases.

I also want to go over the flow of funds happening when you create a charge with destination:

1/ You create the $100 charge with the `destination` parameter and take $10 as an application fee.

2/ This deposits $100 minus Stripe's fees ($3.2 in the US) in your pending balance.

3/ We create a transfer automatically for those funds to remove $100 from your balance and send it to the connected account.

4/ A payment (py_XXX) is created on the connected account corresponding to those $100 minus your application fee added to their pending balance.

5/ That application fee is then deposited in your pending balance.

The connected account will then get their transfers automatically by default unless they, themselves, switched to manual transfers.

I hope this clarifies the situation a bit!

All the best, 

Remi

[1] https://stripe.com/docs/connect/payments-fees#charging-through-the-platform 

[2] https://dashboard.stripe.com/account/transfers 

[3] https://stripe.com/docs/connect/payments-fees#collecting-fees 

[4] https://stripe.com/docs/api#create_transfer

--
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...@lists.stripe.com.
To post to this group, send email to api-d...@lists.stripe.com.
Visit this group at http://groups.google.com/a/lists.stripe.com/group/api-discuss/.

[roy whitburg rwhitburg]

Awesome! I think I got it. There are actually two different transfers going on. The transfer to the platform's bank account must me manual to ensure that the transfer from my Stripe account to the Connected account can take place. 

Expanding on the process you nicely outlined above, could you please answer my following questions as they relate to the API (or Webhooks)? 1) Where does a foreign conversion fee occur in this process? As I understand it, simply, if the payer's and Connected receiver's account are in a different currency, then there's a 2% charge, but I'd like to see exactly where/when that occurs in the process. 2) How can the platform be certain, IN ADVANCE, that there will be a FC fee (so we can increase our application fee to compensate for it)? And how can the platform be certain AFTER THE FACT that an FC fee did in fact occur? 3) How long does the entire "charge" process usually take (I.e., when can I display to the user a "Success!" message)? I assumed this was in the Charge object creation response. But might there be delays and how is the platform notified of the status (during that initial script run and subsequent to that) if those delays occur (I.e, What is Stripe's equivalent to paypal's status notifications)?

Thanks Again.

[Remi J.]

Hey Roy,

1) Where does a foreign conversion fee occur in this process? As I understand it, simply, if the payer's and Connected receiver's account are in a different currency, then there's a 2% charge, but I'd like to see exactly where/when that occurs in the process.

=> We have a support article covering this in details with concrete examples: https://support.stripe.com/questions/how-do-currency-conversions-work-on-connect

I tend to advise users to try the flow themselves with a few examples. What I do on my end is that I create a few Test accounts such as one in France with the default currency set to EUR, one in Canada with the default currency set in CAD and another one in Canada with the default currency set to USD. All of that can be done in Test mode and choosing the right values in the dashboard.

Then, I'd charge customers in multiple currencies (USD, EUR, CAD, GBP, etc.) on behalf of each connected account to see what the flow of funds is and how it differs in each case to better grasp the logic if needed.

2) How can the platform be certain, IN ADVANCE, that there will be a FC fee (so we can increase our application fee to compensate for it)?

And how can the platform be certain AFTER THE FACT that an FC fee did in fact occur?

=> With standalone accounts it's a bit complicated unfortunately because you don't know whether they have a USD bank account or not. For example if you're a platform in the US you have a USD bank account. You can then have a Canadian account connected to your platform with only a CAD bank account in which case charging customers in USD would lead to an FX fee. But if they have a USD bank account too (which is allowed in Canada) then there would be no FX fee as we'd keep the flow of funds in USD and you can't really know in advance.

After the fact though you do know. This is covered in the Balance Transaction object [1] associated with the charge (txn_XYZ). You can retrieve it [2] or directly expand it [3] when you create the charge. This will tell you in which currency and for which amount the balance transaction was, compared to the charge. If the currencies differ then you know an FX fee was involved.

3) How long does the entire "charge" process usually take (I.e., when can I display to the user a "Success!" message)? I assumed this was in the Charge object creation response.

But might there be delays and how is the platform notified of the status (during that initial script run and subsequent to that) if those delays occur (I.e, What is Stripe's equivalent to paypal's status notifications)?

You, as the platform, are the one creating the charge. You know immediately whether the charge succeeded or not. If it was accepted by the bank, you get a Charge object [4] back from us and at that point you know the funds are yours (even though they will be pending for 2 days in the US). Otherwise, if the bank refuses the charge you'd get an error [5] back that you'd use to display this to the customer.

We do offer webhooks [6] that allow you to listen for events happening in your own account or the connected ones but it should be seen as a way to monitor activity or confirm the data you have in your own database. You don't need to wait for events to confirm a charge succeeded or failed.

I hope this helps but let me know if you have any other question!

All the best,

Remi

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

[2] https://stripe.com/docs/api#retrieve_balance_transaction

[3] https://stripe.com/docs/api#expanding_objects

[4] https://stripe.com/docs/api#charge_object

[5] https://stripe.com/docs/api#errors

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

[roy whitburg rwhitburg]

This is some great information, Remi! I especially like the option to Expand objects to save some API calls. 

1) You mention "If the currencies differ then you know an FX fee was involved."

I see the there is a fee_details array in the Balance Transaction response that contains the Stripe fee. Can I rely on that array to contain any FX fee details as well, or am I better off comparing the currencies as you mentioned?

2) Looking at the Account Object found here ( https://stripe.com/docs/api#account ), it returns the "default_currency" and "currencies_supported" properties.

How does this sound as a solution to counter the complication in determining the proper Application fee amount in advance (to compensate for a potential FX fee). We first rely on the default_currency. If that is different than the payer's currency, then we increase the application fee 2%. Then, if after the fact, it's discovered in the Balance Transaction that the same currency as the payer's was used, and no FC fee occurred, we could auto refund. My question is - if this were to occur frequently, is there an expense to issuing refunds this way, either financial or in the form of raising a red flag in Stripe's eyes (i.e. Too many refunds = something fishy/unprofessional, etc.).

Thanks again!

[Remi J.]

Hey Roy!

1/ So the FX fee is always applied *before* we take our fee so it's not part of the `fee_details` hash. You need to check at the currency on the charge and the balance transaction and if they differ you know an FX fee was involved.

2/ This is definitely easier to do it this way and there is no real cost in refunding the application fee partially as needed beyond potential confusion for your connected users when they look at the dashboard I suppose. It might be worth considering a larger application fee in general to balance it out instead of over-complicating your calculations and it's more transparent for your users too but it can be a problem if the fee increases too much by default.

All the best,

Remi

Visit this group at https://groups.google.com/a/lists.stripe.com/group/api-discuss/.

[roy whitburg rwhitburg]

Thanks a lot, Remi. I've asked these questions to others before, but only your answers have been crystal clear. Thanks again for taking the time.

[roy whitburg rwhitburg]

Hi Remi, can a "refund" be given to a Connected account? I thought about it and doesn't "refund" mean money returned to the original PAYER? If my solution to the FX complication is too always add an extra 2% on my application fee to cover for a possible FX fee, then how do I then return that 2% to the CONNECTED account (upon learning an FX wasn't applied), if "returning" is an action that is exclusively for Payers, not Connected accounts?

Thanks.

[Remi J.]

Hey Roy,

You would use the Create Application Fee Refund API for this: https://stripe.com/docs/api#create_fee_refund

All the best,

Remi

[roy whitburg rwhitburg]

Hi Remi, As I've started coding this, I realize I don't have quite the grip I thought I did. 

1) What are the CC numbers we can test foreign customers with? That is, if my platform is US-based and I want to test EUR-paying CUSTOMERS or CAD-paying customers, how do I do it?

2) I'm suffering from Currency Property overload! You say below, "If the currencies differ, then you know an FX fee was involved."

Bottom line is I don't know which currency property I'm supposed to be comparing with the Balance Transaction's currency property in order to determine whether there was an FX fee - specifically where that currency info comes from. You mention it's the currency property that I populate when I created the Charge Object with, but I'm not clear where that information is supposed to come from. I thought that was our business decision, and it would always be in USD (but is that supposed to reflect the Customer's currency or he Connected account's currency somehow? That is, are we expected to calculate the price in a foreign currency, and then Charge? That seems dangerous.). I'm assuming the Balance Transaction's currency property only indicates the Connected account's currency, right? So, there's no way for me to know if the Customer's currency is different, because I still don't know what the Customer's currency is or where it's supposed to have come from. Therefore, I can't know if there was an FX fee.

What currency am I supposed to put into the charge object? Is this just simply our business decision or are we bound to something else, e.g. the Customer's Currency or the Connected Account's currency.

Sorry if this seems scatterbrained. I'm not following.

[Remi J.]

Hey Roy,

1/ We don't really have test cards for foreign countries at the moment unfortunately. The exception is that our JCB cards are from Japan so you could use those but only when charging in the US as they are not supported on European accounts.

You don't need a foreign card though. What you need is to charge in a currency other than USD to see the FX. You'd use one of our test cards and charge 10000 yens for example if you want to see how FX work.

2/ Depending on whether you charge via `destination` [1] or directly [2] you'd see a different behavior in your dashboard (or theirs). When you want to see if an FX was involved you need to look at a given Charge object [3] and then the corresponding Balance Transaction object [4]. Both of those have a `currency` property. If they are the same it means no FX was involved and if they differ it means there was an FX involved.

Let's forget Connect temporarily. If you charge a customer in USD in your platform you will see the charge object with the currency set to USD. If you then look at the associated balance transaction, you'll also see the currency property set to USD. This means we didn't FX since there was no currency conversion. If you charge 100€ though, you'll see the currency property set to EUR while the balance transaction will have a currency property set to USD. This indicates that there was an FX here since we converted a charge from EUR to USD. The amount on the balance transaction corresponds to the converted amount in USD from the original amount in EUR (after FX).

The same logic applies with Connect in the end except that depending how you create the charge it's either the charge that's converted or the corresponding transfer instead.

I'd recommend setting up a few example managed or standalone accounts in different countries with different default currencies. Then, create a few charges in USD, EUR, GBP, etc. to really see how it all works out in your dashboard and the connected users' in the end.

I hope this helps!

Remi

[1] https://stripe.com/docs/connect/payments-fees#charging-through-the-platform

[2] https://stripe.com/docs/connect/payments-fees#charging-directly

[3] https://stripe.com/docs/api#charge_object

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

Visit this group at https://groups.google.com/a/lists.stripe.com/group/api-discuss/.

[roy whitburg rwhitburg]

Hi Remi,

"If you charge 100€..."

That's where I'm confused. I will always only know what the price is in USD. So...

1) How do I know what currency to charge in? I'm guessing this will ALWAYS be available in the Customer Object's Currency Property because Stripe has gained that info from the Checkout? If so, does this Checkout currency value specifically come from ...

A) what I populated in the Checkout property field, or 

B) what Stripe has ascertained after "seeing" what creditcard/bank the customer is actually using?

2) Further, I thought it was not recommended to try to calculate the conversion on our end? I thought that was part of Stripe's service, no?

3) If we're supposed calculate the conversion, then how do I determine the current rate accurately? Through some outside commercial source? Which one?

[Remi J.]

Hey Roy,

Sorry about the confusion here, I think we're talking about different things. I was trying to clarify when FX can happen and how to detect it in your code after the fact. It's not really what you have to do in the end, just a possibility.

You charge in the currency you want here as you're the one calculating the amount to charge and the currency to charge in. This is not related to Checkout specifically. What I've seen some users do here is to ask the customer which currency to charge in before collecting the card details and then charge in that specific currency. Others would simply always charge in their own currency. You don't *have* to ask the customer. If you always want to charge in USD you can do so and the decision is yours.

What we offer on our end is to convert the funds for you if you charged the customer in a currency that you don't have a bank account for. This means that if you charge in USD we do nothing and if you charge in EUR or JPY then we'll automatically convert those funds for you to USD.

Now to get back to your situation, if you charge using `destination` through your US platform on behalf of international users here's what can happen:

1/ Connected user has a US account and a USD bank account. There's no FX involved anywhere.

2/ Connected user has a GB account and a USD bank account. There's no FX involved anywhere.

3/ Connected user has a GB account but they don't have a USD bank account. FX is involved in that case.

Let's say that you charge $100 today on your US platform and take $10 as an application fee. For #1 and #2, you'd end up with $6.8 ($10 app fee minus $3.2 Stripe fee) and the connected account would end up with $90. No FX involved and flow of funds is pretty straightforward. If you look at the balance transaction associated with the original charge on your platform you'd see `currency: "usd"` that confirms no FX was involved.

For #3 it's a bit more complicated and corresponds to what you want to detect. Since the connected account doesn't have a USD bank account we'll have to convert to their default currency. For simplicity's sake, let's assume they have only a GBP bank account and it's their default currency. It means you charged $100 but we need to convert to GBP. This means that you end up with £66.62 in your account. This amount is *after* conversion from USD to GBP and includes the FX fee in it. This is also *before* we take our own fee from the transaction. We also take our fee (£1.13) which means you end up with £65.49 GBP in your balance. If you look at the balance transaction for that charge you'll see that you now have `currency: "gbp"` as it was converted. That's the logic you use to detect it in the first place.

We then transfer out the full amount of the charge to the connected account so you'll see -£66.62 in your balance which leaves you at -£1.13 in the end. The connected account then get those £66.62 and we take you $10 application fee from it. This is also FX-ed for the connected account. This means we take your fee in GBP as £6.66 so that you end up with the expected $10 application fee.

In the end, the connected account earned £59.96 after we took your fee and you as the platform got $10 as an application fee and -£1.13 for our fee in another currency.

The last step is a know quirk with the API and FX right now. This means that, as a platform, you'll end up with negative balances in other currencies that you don't have a bank account for. We recommend to simply ignore those negative balances for now while we work on better plots to fix this situation. You can also ask us to convert those to USD regularly by contacting support [1] until then if you don't want to see those build over too much.

I hope the full example helped clarify the situation here. Usually I recommend to play with the API and create such situations as #1 to #3 to better understand the flow of funds, who pays what, as it sinks in way better when seeing it in your dashboard and the connected accounts' (at least it does for me).

Let me know if you have any other question here though!

All the best,

Remi

[1] https://support.stripe.com/email

[roy whitburg rwhitburg]

Hi Remi, 

1) "if you charge in EUR or JPY then we'll automatically convert those funds for you to USD."

So, when I create the Charge object, I assume that means I would assign EUR to the currency property, but then what do I assign to the "amount" property? Say, I know the item is $10 USD. I don't know that amount in EUR at charge time.

2) You say, "if you charge in USD we do nothing...If you always want to charge in USD you can do so and the decision is yours."

Above, you said, "[The Balance Transaction Response] will tell you in which currency and for which amount the balance transaction was, COMPARED TO THE CHARGE (my emphasis). If the currencies differ then you know an FX fee was involved."

Do you see where these statements seem to contradict? It seems that technically, if "the decision is mine" to assign any currency to the Charge object I want, then if I happen to charge in the same currency that a foreign exchange is ultimately converted to, then, by your rule, no FX fee has taken place, because the charge currency matches the Balance Transaction currency, right? Conversely, if all players have US accounts, and I, for chuckles, charge in JPY, then, by your rule, an FX fee has occured (because the Charge and BT currencies differ), when, in reality, no foreign conversion has taken place. What am I missing?

3) Right now, I'm not even going to try to wrap my head around "you'll end up with negative balances in other currencies that you don't have a bank account for" until I get a grip on my current issue. I'm sure that will come up later ;-)

 

4) With each post, I'm a little worried that my harping on the same question is eventually going to scare you away. Hopefully not. I do appreciate your help, and I hear what you're saying about me testing different scenarios to get a better understanding, but I need to be able to properly create the charge object first, and I know that what I've got right now. isn't right.

5) Additionally, just as a suggestion to Stripe, it would be awesome if, for some of the more complicated examples (like some you've provided and a couple here: https://support.stripe.com/questions/how-do-currency-conversions-work-on-connect ), they contained language as the scenario relates to the API objects and properties directly. I really don't see much talk of FX fees anywhere. At least not in a very detailed form.

[Remi J.]

Hey Roy!

1/ This is up to you here. Most companies that do that have their own system for calculating the exchange rates. Our support article [1] about currency has a section called "Stripe Conversion Fees" which says:

"You may use an online resource for conversion calculation, such as Open Exchange Rates or Google’s Currency Converter, to help estimate current market rates. However, these numbers can fluctuate and they may not reflect Stripe’s rates at the time of processing a payment."

As I said before though you really don't *have* to do that. You can simply charge everyone in one currency instead. Or at least the currency decided by the seller for his products.

I want to reiterate this: you don't need to charge anyone in another currency. It was just to give a full picture of the flow.

2/ On that one, you lost me completely here I'm sorry. I don't see where my statements contradict so it's hard to clarify. You are the one charging. This means *you* decide the currency and the amount to charge the *customer*.

If you decide to charge $100 USD then, on your website, the customer who pays knows he will be charged $100 USD. He has no idea whether it's converted to EUR or GBP behind the scenes as it doesn't concern him. What he sees is that on his bank statement you told his bank "Give me $100 USD" and that's what the bank takes from their account.

Now the currency you decide to charge the customer in is one thing. But then internally we need to pay out those funds to someone. That's where the conversion might happen. If you charge on behalf of a French user with only an EUR bank account, we can not send them USD. The only currency we can send them is EUR. In that case we have to convert the funds you charged to EUR. When that happens there is an FX. And when that happens, the balance transaction is in EUR while the charge itself that you created is in USD.

The FX step is really here to convert funds charge in currency A to currency B that the seller has a bank account in. If he has a bank account in currency A there is no conversion.

3/ 4/ You're not going to scare me away, I'm happy to help! But we might want to move away from the api-discuss list as this might become a bit specific to your business and what you want and be less useful for everyone else.

5/ This article focuses on the logic of conversion. I think that adding API terms would complicate the matter because most people reading it want a higher level understanding and might not be familiar with the API itself.

If it's still not clear, I would really recommend you to take some time to create 2 accounts, one FR and one US and simply charge $100 on their behalf and *see* in the dashboard the flow of funds. I know it's frustrating to not fully understand upfront but I've been through this flow with other users before and there's usually an aha-moment when you see both charges in your platform and one is converted and not the other. And then playing with new amounts makes things even more concrete.

[1] https://support.stripe.com/questions/which-currencies-does-stripe-support

[roy whitburg rwhitburg]

Hi Remi.

" we might want to move away from the api-discuss list"

I'm ok with that. Do you have a suggestion? Do you have a direct phone number where I can reach you (I'd really prefer not to have to start from scratch with someone else if possible)? When is a good time of day, and which timezone are you in? I'm going to create a couple foreign accounts, as per your suggestion. Then probably get back in a few days. #2 really is my problem point, and it sounds like the phone may the best option for ironing that out.

[Remi J.]

Hey Roy,

You can simply reply to my email address privately if you have more questions! I wouldn't be able to hop on the phone with you directly but I'm fairly certain that doing the flow with a few example charges on your end will clear 95% of your questions. Once you have that setup you can share screenshots and ids of concrete charges and conversions if you are still confused and I'll be able to clarify for you!

All the best,

Remi