#jairo_api

1 messages · Page 1 of 1 (latest)

raven marshBOT
#

👋 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/1493381692898148444

📝 Have more to share? Add more details, code, screenshots, videos, etc. below.

drifting ice
#

Hi there. Could you describe what you want to do in a bit more detail so I can offer a recommendaiton?

eager sphinx
#

Thanks for jumping in 🙏

Let me describe the flow more clearly:

We are building a SaaS platform for sports academies (multi-tenant).

Flow:

  1. Each academy signs up and connects their Stripe account (we plan to use Stripe Connect Standard)
  2. Parents pay the academy through our platform (monthly fees, events, etc.)
  3. We take a commission on each transaction (around 3% + fixed fee)

What we want:

  • Money goes directly to the academy
  • We automatically take our commission
  • Keep onboarding simple for academies (non-technical users)

Key questions:

  1. For this use case, is it better to use:

    • Direct Charges
    • Destination Charges
    • or Separate Charges and Transfers?

  2. What is the best way to implement commissions reliably?

    • application_fee_amount?
    • or another approach?

  3. Any best practices for handling:

    • failed payments
    • retries
    • refunds
    • disputes

Goal:
We want a clean, scalable architecture from day one and avoid reworking payments later.

Really appreciate your guidance here
Additional context:

  • Our clients are mostly non-profit sports associations (not companies)
  • We process data of minors (ages 5-18), so GDPR/COPPA compliance matters
  • We want to go white-label: academies should never see Stripe directly
  • We plan to use Payment Element for the checkout form
  • We're considering Custom accounts + Embedded Components so everything stays inside our platform
  • Launch market: Spain (EUR), then expanding to USA Hispanic market (USD) and Latin America
  • Expected scale: 500-1,000 academies in year 1, each with 50-200 paying parents
drifting ice
eager sphinx
#

Thanks! That confirms our approach 🙌

Follow-up question: we want to go fully white-label so academies never interact with Stripe directly.

We're considering:

  1. Custom accounts (instead of Standard) + Embedded Components for onboarding, payments dashboard, and payouts — all inside our platform
  2. Payment Element for the parent checkout
  3. Custom email domain (payments@ourdomain.com)
  4. Custom checkout domain (pay.ourdomain.com)

Is this the right path for a white-label setup? Any gotchas we should watch out for when using Custom accounts + Embedded Components at scale?

drifting ice
#

We want to go white-label: academies should never see Stripe directly

This is somewhat at odds with Standard Connect, since they have access to the Stripe dashboard and Stripe generally owns collection of requirements for standard accounts

#

Custom and Standard are quite different in terms of behavior - I would recommend having a look at this guide: https://docs.stripe.com/connect/accounts to get an understanding of who owns liability, onboarding, and so on with the different setups

#

Custom accounts make it easier to create a white label setup, but your platform also has more liability

eager sphinx
#

That makes total sense — that's exactly why we're planning to move away from Standard.

So to confirm: for a fully white-label setup, should we go with:

  • Custom accounts (where we control onboarding via Embedded Components)
  • Direct Charges + application_fee_percent for commissions
  • Payment Element for the parent-facing checkout

Is this the recommended architecture for our use case? And are there any important differences between Custom and Express we should consider?

drifting ice
#

Again, to understand the differences between Custom and Express, I'd recommend using the table above as a starting point since it is laid out very cleanly.

You should not use direct charges with custom accounts

#

is there a specific reason why you want direct charges with this connect setup, or is it just that the path to collecting platform fees is clear?

#

Probably you would use Destination Charges + on_behalf_of if you want the connected account to be the Merchant of Record. You can take your fee when setting up the destination charge. see transfer_data here

eager sphinx
#

Got it — no Direct Charges with Custom accounts.

So what's the recommended charge type for our case?

  • Destination Charges?
  • Or Separate Charges and Transfers?

Our key requirement: the parent pays, the academy receives the money in their bank account, and we keep a commission automatically. All white-label.

Which approach do you recommend?

One more thing — what are the practical consequences of using Custom accounts for a platform like ours?

We want our clients (sports academies) to see our platform as the single entry point for everything. But we're a small startup and don't want to take on excessive liability or compliance burden.

Is there a middle ground where we get the white-label experience without taking on too much risk? For context, we process data of minors (5-18 years old) so compliance matters a lot to us.

#

That clarifies everything — thanks!

No specific reason for Direct Charges, we just started there because the application_fee path was straightforward.

So our final architecture will be:

  • Custom accounts (controller properties / Accounts v2)
  • Destination Charges + on_behalf_of (academy as merchant of record)
  • application_fee_amount for our platform commission
  • Payment Element for parent checkout
  • Embedded Components for academy dashboard

This gives us white-label + the academy as merchant of record + automatic commission. Perfect.

One last question: with this setup and Subscriptions (recurring monthly fees from parents), do we create the Subscription on our platform account with transfer_data pointing to the connected account? Or is there a different pattern for recurring payments with Destination Charges?

Thanks again — this has been incredibly helpful 🙏

drifting ice
#

transfer_data means destination charges. specifying a Stripe account as transfer_data.destination means you're using destination charges

eager sphinx
#

Hey palamedes, thanks for all the guidance — it's been incredibly valuable.

Based on everything you've explained, here's our final architecture plan. I'd love your confirmation that we're on the right track:

We'll use Express accounts (not Custom) to keep liability manageable for a startup, but we'll create a "white-label experience" by layering Embedded Components on top. The idea is that academies interact entirely within our platform and never need to visit the Express Dashboard.

Specifically:

  1. Express accounts for each academy (Stripe handles onboarding, identity verification, and compliance updates automatically)
  2. Destination Charges + on_behalf_of (academy as merchant of record)
  3. application_fee_amount for our platform commission on each payment
  4. Payment Element for the parent-facing checkout (branded with our colors and domain)
  5. Embedded Components inside our Director Panel:
    • Account Onboarding (academy signs up without leaving our platform)
    • Payments (academy sees their received payments)
    • Payouts (academy sees transfers to their bank)
    • Balances (real-time balance)
    • Notification Banner (compliance alerts)
  6. Custom email domain (payments@koinoniasport.com)
  7. Custom checkout domain (pay.koinoniasport.com)

The academy does everything inside Koinonia. They technically have an Express Dashboard, but we never send them there — all the functionality they need is embedded in our platform via Connect Components.

Does this approach make sense? Are there any gotchas with using Embedded Components on Express accounts that we should know about?

Thanks again for your time

drifting ice
#
  1. I just want to point out that you can also specify a fee by transfer_data.amount_percent docs
raven marshBOT
vestal hull
#

Hi @eager sphinx I'm taking over this thread, give me a sec to catch up

#

Just want to add that when using Embedded Components on Express Accounts, Express accounts must authenticate via Stripe (SMS/OTP) for sensitive actions, unlike custom account which supports disable_stripe_user_authentication it's not bypassable for express accounts.