Build Marketplace Payment Flows with Atlas

Use this flow when your marketplace needs to onboard sellers, isolate balances by seller, collect funds into the right context, and later pay out from the correct sub-account.

✅ Before you start

Complete these steps before you implement the marketplace flow:

Confirm that your programme is using the Atlas for Platforms model.
Confirm whether your account is approved for the collection and payout capabilities you want to expose.
Decide what seller identity and onboarding data you need to collect before operational actions are enabled.
Prepare to store the returned sub-account IDs, wallet IDs, and account details for each seller.
Register webhook endpoints so you can reconcile inbound funds and seller payouts without polling.

📚 Use this page with the recipe

This guide explains when to use the marketplace flow and the minimum sequence. For the implementation walkthrough, use the recipe:

Build Marketplace Payment Flows with Atlas Recipe →

The marketplace workflow

This use case follows a simple sequence:

Create a sub-account for each seller or downstream business you need to onboard.
Complete onboarding and wait for approval before you allow that seller to receive funds or pay out.
Create wallets in that seller context for the currencies the marketplace needs to support.
Issue account details when the seller needs to receive funds into their own scoped collection flow.
Use the same seller context for statements, beneficiaries, payouts, and balance views.

What makes this use case different?

Unlike a direct own-funds integration, a marketplace flow needs you to:

isolate ledger activity by seller
keep collections, balances, and payouts tied to the correct downstream customer
respect compliance approval before enabling operational actions for each seller

Optional: Add seller payouts

If your marketplace pays sellers onward to external bank accounts, create beneficiaries and send payouts in the same seller context that owns the wallet.

If your programme requires third-party payouts, confirm the required operational approval before you expose that flow in production.

Where to go deeper

Use the product guides when you need implementation detail for a specific step:

Troubleshooting

Issue	What to check
Seller cannot receive or transact	Confirm the seller has completed onboarding and reached the approved operational state.
Funds or payouts hit the wrong seller	Verify whether the `X-Sub-Account-Id` header and wallet belong to the intended seller context.
Seller bank details are incomplete	Display the exact returned account details for the corridor, including any required reference or routing value.
Payout capability is blocked	Check whether your account is approved for third-party payout flows and whether the seller context is active.

Next steps


Embedded Sub-Accounts → Start with the seller-isolation pattern used in embedded marketplace flows.	Login as a Sub-Account and Run a Scoped Action → See how to operate safely inside one seller context at a time.

Talk to Verto

Get help with authentication, receive flows, wallets, FX conversion, payouts, or Atlas platform setup.

Plan your go-live

Review the requirements you need before moving your integration into production.