How can I integrate a checkout API into a marketplace platform with split payouts and card payments?

To integrate a checkout API into a marketplace with card payments and split payouts, you typically need a setup that supports:

1. Collecting payment from the buyer
2. Allocating funds between multiple sellers/your platform
3. Handling payouts, refunds, and disputes
4. Complying with marketplace/KYC requirements

1) Choose the right payment model

Most marketplaces use one of these patterns:

A. Platform collects, then splits later

• Buyer pays your platform.
• You hold the funds temporarily.
• You transfer seller shares later.
• Good if you need more control over order fulfillment.

B. Direct split at checkout

• Payment is automatically split between recipients when the charge succeeds.
• Easier for settlements, but depends on your PSP support.

C. Separate charges and transfers

• Charge the customer once.
• Create transfers to sellers after payment confirmation.
• Common with providers like Stripe Connect.

For marketplaces, “separate charges and transfers” or “destination charges” are the most common.

---

2) Use a marketplace-capable payment provider

Pick a payment gateway that supports:

• Card processing
• Split payouts / sub-merchants
• Seller onboarding/KYC
• Payouts to bank accounts
• Refunds and chargebacks handling
• Webhooks

Examples:

• Stripe Connect
• Adyen for Platforms
• PayPal Commerce Platform
• MangoPay
• Checkout.com marketplace offerings

---

3) Typical marketplace payment flow

Step 1: Onboard sellers

Each seller needs an account/sub-account so funds can be routed and paid out.

• Collect identity/business info
• Verify bank account
• Complete KYC/AML checks

Step 2: Create checkout session/payment intent

When buyer checks out:

• Your backend calculates:
  • item subtotal
  • platform fee
  • seller split(s)
  • tax/shipping if applicable
• Create a payment object with:
  • amount
  • currency
  • metadata (order ID, seller IDs)
  • split instructions

Step 3: Take card payment

Use the provider’s hosted checkout or payment elements.

• Hosted checkout reduces PCI scope
• Save only tokens, not raw card data

Step 4: Confirm payment

After authorization/capture:

• Mark order as paid
• Store transaction IDs
• Trigger fulfillment

Step 5: Payout or transfer funds

Depending on the model:

• Provider automatically pays out to sellers
• Or your backend creates transfers to connected accounts

---

4) Example architecture

Frontend

• Cart page
• Checkout page
• Hosted payment page or embedded card form

Backend

• Order service
• Pricing/split calculation service
• Payment orchestration service
• Webhook handler
• Payout reconciliation service

Payment provider

• Payment intents / charges
• Connected accounts
• Transfers/payouts
• Disputes/refunds

---

5) Important implementation details

Split logic

Define how you split:

• Percentage-based split
• Fixed fee + variable commission
• Multi-vendor cart split
• Taxes and shipping allocation

Example:

• Buyer pays: $100
• Seller A gets: $70
• Seller B gets: $20
• Platform fee: $10

Webhooks

Always use webhooks to confirm:

• payment succeeded
• payment failed
• payout paid
• chargeback opened
• refund completed

Do not rely only on frontend success callbacks.

Refunds

You need a policy for:

• full refunds
• partial refunds
• seller-funded refunds vs platform-funded refunds

Chargebacks

Prepare for card disputes:

• store evidence
• map transactions to orders/sellers
• decide how chargeback liability is allocated

Compliance

You may need:

• PCI compliance
• KYC/AML for sellers
• tax reporting
• money transmission/legal review depending on country

---

6) Minimal integration flow example

A common flow looks like this:

1. Seller is onboarded and connected account created
2. Buyer clicks “Pay”
3. Backend creates payment intent:
   • amount = order total
   • application/platform fee = commission
   • destination = seller account or transfer destination
4. Frontend confirms card payment
5. Provider sends webhook on success
6. Backend marks order paid
7. Funds are transferred/payouts scheduled

---

7) If you use Stripe Connect as an example

You would usually:

• Create a connected account for each seller
• Create a PaymentIntent on the platform
• Use transfer_data[destination] or separate transfers
• Set application_fee_amount for your commission
• Listen to webhooks like payment_intent.succeeded, charge.refunded, transfer.paid

---

8) Best practices

• Use idempotency keys for payment creation
• Keep split logic in your backend, not the client
• Use webhooks for final state changes
• Reconcile orders, payments, transfers, and payouts daily
• Support asynchronous payment states
• Build strong logging and audit trails

---

9) Suggested implementation sequence

1. Pick a marketplace-capable PSP
2. Define seller onboarding/KYC flow
3. Build order and split calculation logic
4. Implement hosted checkout/card capture
5. Add webhook processing
6. Implement transfer/payout reconciliation
7. Add refunds/disputes handling
8. Test with sandbox mode end-to-end

If you want, I can also give you:

• a Stripe Connect example flow
• a sample backend API design
• or a database schema for marketplace payouts