> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tazapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Marketplaces

> Use named Collection Accounts with entity IDs to attribute buyer payments to the right seller and drive your merchant ledger

Marketplaces with international sellers need a way to attribute each buyer payment to the right seller so reconciliation is clean and payouts go to the right place. Tazapay provisions a **named [Virtual Account](/collection-accounts/overview/introduction) per seller** (linked to an [entity](/getting-started/core-concepts/creating-entities) ID), so every incoming [collect](/api-reference/tazapay-api/collects) carries the seller's entity ID in the [webhook](/collection-accounts/incoming-payments/webhooks). The marketplace uses that entity ID to credit the right seller in their own ledger and trigger payouts from their Tazapay balance when the seller's payout cycle runs.

Tazapay does not maintain per-seller balances or per-Virtual Account balances — all collects credit the marketplace's Tazapay [balance](/getting-started/core-concepts/balances/overview). The seller-level accounting lives in the marketplace's ledger.

## How Tazapay Helps

<CardGroup cols={2}>
  <Card title="Named Virtual Account per Seller" icon="id-card">
    Each seller gets their own Virtual Account linked to their entity ID — every collect is automatically tagged so your ledger knows exactly who was paid.
  </Card>

  <Card title="Entity ID on Every Collect" icon="tag">
    The `collect.succeeded` webhook carries the seller's entity ID and payment reference, giving your system the signal it needs to credit the right seller.
  </Card>

  <Card title="Local Rails + SWIFT" icon="arrow-right-arrow-left">
    Provision local Virtual Accounts (FAST, ACH, SEPA, Faster Payments, NEFT/IMPS) for in-country buyers, or SWIFT Virtual Accounts for cross-border — buyers pay at local rail cost and speed.
  </Card>

  <Card title="Marketplace-initiated Payouts" icon="money-bill-transfer">
    Once your ledger shows a seller is due for payout, trigger a [payout](/payouts/overview/overview) from your Tazapay balance to the seller's bank account on their cycle.
  </Card>
</CardGroup>

***

## Example: ShopHub Marketplace (UAE)

ShopHub is a marketplace operating in UAE. Each seller is onboarded as an entity with a named Virtual Account. Because each Virtual Account is mapped to a specific seller, any payment that lands on a Virtual Account is automatically attributed to that seller.

<Steps>
  <Step title="Onboard each seller as an entity">
    Seller X is onboarded as an entity on ShopHub's Tazapay account. See [Connected Accounts](/getting-started/core-concepts/account/overview).
  </Step>

  <Step title="Provision a named Virtual Account per seller">
    ShopHub calls [Create Collection Account](/api-reference/tazapay-api/create-collection-account) for Seller X, scoped to their entity ID (`SELLER_X`). This Virtual Account has a unique account number.
  </Step>

  <Step title="Buyer pays at checkout">
    A buyer orders an iPhone case worth AED 100 from Seller X. ShopHub directs the payment to Seller X's Virtual Account.
  </Step>

  <Step title="Collect fires with the seller's entity ID">
    Tazapay credits ShopHub's Tazapay balance and fires a `collect.succeeded` webhook identifying the Virtual Account (`SELLER_X`) and the amount (AED 100).
  </Step>

  <Step title="ShopHub credits the seller in its ledger">
    The Virtual Account maps to Seller X, so ShopHub deducts its 10% commission and credits AED 90 to Seller X's balance in its ledger.
  </Step>

  <Step title="Payout to seller on cycle">
    On Seller X's weekly payout day, ShopHub reads Seller X's ledger balance (say AED 1,847, accumulated across many orders) and triggers a payout via the [Create Payout](/api-reference/tazapay-api/create-payout) API — from ShopHub's Tazapay balance — to Seller X's external bank account.
  </Step>
</Steps>

## Flow Diagram

<Frame>
  <img src="https://mintcdn.com/tazapay-58ae360f/hou37QksFwdJPvtp/images/diagrams/flow-marketplace.png?fit=max&auto=format&n=hou37QksFwdJPvtp&q=85&s=83860468badc2098a7fe301ac6aa4667" alt="Marketplace flow" width="4040" height="960" data-path="images/diagrams/flow-marketplace.png" />
</Frame>

***

## Why this matters

<CardGroup cols={3}>
  <Card title="Clean attribution" icon="check">
    Every collect arrives with the seller's entity ID — no manual matching, no ambiguous references. Your ledger knows exactly who earned what.
  </Card>

  <Card title="Scales to any seller count" icon="layer-group">
    One named Virtual Account per seller, no matter how many sellers you onboard. Attribution is handled at the collection layer, not reconstructed after the fact.
  </Card>

  <Card title="Marketplace-controlled payouts" icon="sliders">
    Your platform triggers each payout via API on whatever cycle works for your sellers — weekly, monthly, or on-demand.
  </Card>
</CardGroup>

***

## APIs Involved

| Purpose                                      | API                                                                                | Endpoint                       |
| -------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------ |
| Onboard a seller                             | [Create Entity](/api-reference/tazapay-api/create-entity)                          | `/v3/entities`                 |
| Provision a named Virtual Account per seller | [Create Collection Account](/api-reference/tazapay-api/create-collection-account)  | `/v3/collection_account`       |
| Track incoming collects (with entity ID)     | [Collect Webhooks](/api-reference/tazapay-api/collect-webhook)                     | `collect.*`                    |
| Pay out to a seller's bank account           | [Create Payout](/api-reference/tazapay-api/create-payout)                          | `/v3/payouts`                  |
| Reconcile a specific transaction             | [Fetch Balance Transactions](/api-reference/tazapay-api/fetch-balance-transaction) | `/v3/balance_transaction/{id}` |

<Info>
  **What Tazapay handles:**

  * Named Virtual Account provisioning per seller, linked to their entity ID
  * Entity ID on every `collect.succeeded` webhook for automatic attribution
  * Local rail and SWIFT coverage for buyer-side payments
  * Marketplace-initiated payouts to seller bank accounts

  **What the marketplace handles:**

  * Seller ledger: tracking each seller's balance from webhook data
  * Commission deduction logic
  * Payout scheduling and seller-facing statements
</Info>