Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in

Collect payments then pay out on your marketplace

Collect payments from customers and pay them out to sellers or service providers on your marketplace.

This guide explains how to accept payments and move funds to the bank accounts of your service providers or sellers. For demonstration purposes, we’ll build a home-rental marketplace that connects homeowners to potential tenants. We’ll also show you how to accept payments from tenants (customers) and pay out homeowners (your platform’s users).

Prerequisites

  1. Register your platform.
  2. Add business details to activate your account.
  3. Complete your platform profile.
  4. Customize your brand settings. Add a business name, icon, and brand color.

Set up Stripe
Server-side

Install Stripe’s official libraries to access the API from your application:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Create a connected account

When a seller or service provider signs up on your platform, create a connected account representing them. The connected account lets you collect their identifying information, accept payments for them, and move funds to their bank account. In our home-rental example, the connected account represents the homeowner.

Create a connected account with prefilled information

Use the /v2/core/accounts API to create a connected account by specifying the connected account dashboard and responsibilities.

Command Line
cURL
No results
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "contact_email": "furever_contact@example.com",
    "display_name": "Furever",
    "defaults": {
        "responsibilities": {
            "fees_collector": "application",
            "losses_collector": "application"
        }
    },
    "dashboard": "express",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        },
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    },
    "include": [
        "configuration.merchant",
        "configuration.recipient",
        "identity",
        "requirements"
    ]
  }'

If you’ve already collected information for your connected accounts, you can prefill that information on the Account object. You can prefill any account information, including personal and business information, external account information, and so on.

Connect Onboarding doesn’t ask for the prefilled information. However, it does ask the account holder to confirm the prefilled information before accepting the Connect service agreement.

When testing your integration, prefill account information using test data.

Create an account link

You can create an account link by calling the Account Links v2 API with the following parameters:

  • account
  • refresh_url
  • return_url
  • type = account_onboarding
  • configurations = recipient and merchant
Command Line
cURL
No results
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "account": 
{{CONNECTED_ACCOUNT_ID}}
,
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient",
                "merchant"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'

Redirect your user to the account link URL

The create Account Link response includes a url value. After authenticating the user in your application, redirect them to this URL to send them into the flow. Account link URLs are temporary and single-use only, because they grant access to the connected account user’s personal information. If you want to prefill information, you must do so before generating the account link. After you create the account link, you can’t read or write information for the connected account.

Security tip

Don’t email, text, or otherwise send account link URLs outside of your platform application. Instead, provide them to the authenticated account holder within your application.

ConnectOnboardViewController.swift
Swift
Objective C
No results
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

Handle the user returning to your platform

Connect Onboarding requires you to pass both a return_url and refresh_url to handle all cases where the account user is redirected to your platform.

Note

You can use HTTP for your return_url and refresh_url while in you’re in a testing environment (for example, to test with localhost), but live mode only accepts HTTPS. Make sure to swap testing URLs for HTTPS URLs before going live.

return_url

Stripe issues a redirect to this URL when the connected account user completes the onboarding flow. That doesn’t mean that all information has been collected or that there are no outstanding requirements on the account. It only means that the flow was entered and exited properly.

No state is passed through this URL. After a user is redirected to your return_url, check the state of the requirements on their account by doing either of the following:

  • Listen to v2.core.account[requirements].updated webhooks.
  • Call the Accounts v2 API and inspect the returned object.

refresh_url

Stripe redirects your user to the refresh_url in these cases:

  • The link is expired (a few minutes went by since the link was created).
  • The user already visited the URL (the user refreshed the page or clicked back or forward in the browser).
  • Your platform is no longer able to access the account.
  • The account has been rejected.

Configure your refresh_url page to trigger a method on your server to call Account Links v2 again with the same parameters, and redirect the user to the new link.

Handle users that haven’t completed onboarding

A user that’s redirected to your return_url might not have completed the onboarding process. Use the /v2/core/accounts endpoint to retrieve the user’s account and check if configuration.recipient.capabilities.stripe_balance.stripe_transfers.status is active. If the status is not active and configuration.recipient.capabilities.stripe_balance.stripe_transfers.status_details.code is requirements_past_due, provide UI prompts to allow the user to continue onboarding through a new account link. For other codes, handle them as needed.

Enable payment methods

View your payment methods settings and enable the payment methods you want to support. Card payments, Google Pay, and Apple Pay are enabled by default but you can enable and disable payment methods as needed.

Before the payment form is displayed, Stripe evaluates the currency, payment method restrictions, and other parameters to determine the list of supported payment methods. Payment methods that increase conversion and that are most relevant to the currency and customer’s location are prioritized. Lower priority payment methods are hidden in an overflow menu.

Accept a payment

Use Stripe Checkout to accept payments. Checkout supports multiple payment methods and automatically shows the most relevant ones to your customer. You can accept payments with Checkout using a Stripe-hosted page or add a prebuilt embeddable payment form directly in your website. You can also create a custom flow (using Payment Element) to accept multiple payment methods with a single front-end integration.

Create a Checkout Session Client and Server

A Checkout Session controls what your customer sees in the Stripe-hosted payment page such as line items, the order amount and currency, and acceptable payment methods.

Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session.

checkout.html
<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

On your server, make the following call to Stripe’s API. After creating a Checkout Session, redirect your customer to the URL returned in the response.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=payment \
  -d "line_items[0][price]"=
{{PRICE_ID}}
 \
  -d "line_items[0][quantity]"=1 \
  -d "payment_intent_data[application_fee_amount]"=123 \
  -d "payment_intent_data[transfer_data][destination]"=
{{CONNECTED_ACCOUNT_ID}}
 \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"
  • line_items - This argument represents the items the customer is purchasing. The items are displayed in the Stripe-hosted user interface.
  • success_url - This argument redirects a user after they complete a payment.
  • cancel_url - This argument redirects a user after they click cancel.
  • payment_intent_data[application_fee_amount] - This argument specifies the amount your platform plans to take from the transaction. The full charge amount is immediately transferred from the platform to the connected account that’s specified by transfer_data[destination] after the charge is captured. The application_fee_amount is then transferred back to the platform, and the Stripe fee is deducted from the platform’s amount.
  • payment_intent_data[transfer_data][destination] - This argument indicates that this is a destination charge. A destination charge means the charge is processed on the platform and then the funds are immediately and automatically transferred to the connected account’s pending balance. For our home-rental example, we want to build an experience where the customer pays through the platform and the homeowner gets paid by the platform.

Checkout uses the brand settings of your platform account for destination charges. For more information, see Customize branding.

This Session creates a destination charge. If you need to control the timing of transfers or need to transfer funds from a single payment to multiple parties, use separate charges and transfers instead. To use separate charges, see Enable other businesses to accept payments directly.

Handle post-payment events Server-side

Stripe sends a checkout.session.completed event when the payment completes. Use a webhook to receive these events and run actions, like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes. Some payment methods also take 2-14 days for payment confirmation. Setting up your integration to listen for asynchronous events enables you to accept multiple payment methods with a single integration.

In addition to handling the checkout.session.completed event, we recommend handling two other events when collecting payments with Checkout:

EventDescriptionNext steps
checkout.session.completedThe customer has successfully authorized the payment by submitting the Checkout form.Wait for the payment to succeed or fail.
checkout.session.async_payment_succeededThe customer’s payment succeeded.Fulfill the purchased goods or services.
checkout.session.async_payment_failedThe payment was declined, or failed for some other reason.Contact the customer through email and request that they place a new order.

These events all include the Checkout Session object. After the payment succeeds, the underlying PaymentIntent status changes from processing to succeeded.

Testing

Test your account creation flow by creating accounts and using OAuth.

Card numberScenarioHow to test
The card payment succeeds and doesn’t require authentication.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
The card payment requires authentication.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
The card is declined with a decline code like insufficient_funds.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
The UnionPay card has a variable length of 13-19 digits.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.

See Testing for additional information to test your integration.

Disputes

As the settlement merchant on charges, your platform is responsible for disputes. Make sure you understand the best practices for responding to disputes.

Payouts

By default, any funds that you transfer to a connected account accumulate in the connected account’s Stripe balance and are paid out on a daily rolling basis. You can change the payout frequency by going into the connected account’s details page, clicking the right-most button in the Balance section, and selecting Edit payout schedule.

Refunds

To issue refunds, go to the Payments page. Select individual payments by clicking the checkbox to the left of any payments you want to refund. After you select a payment, Stripe displays a Refund button in the upper-right corner of the page. Click the Refund button to issue a refund to customers for all payments you have selected.

Note

Connected accounts can’t initiate refunds for payments from the Express Dashboard by default. If your connected accounts use the Express Dashboard, you can either process refunds for them, or enable them to process refunds by customizing Express dashboard features.

See also

Was this page helpful?
YesNo