> ## Documentation Index
> Fetch the complete documentation index at: https://vivawallet-sdk-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Marketplace Client: Multi-Seller Platform Integration

> The Marketplace client enables platform operators to manage sellers, payment orders, transactions, and fund transfers across their marketplace.

The `Marketplace` class is built for platform operators running multi-seller marketplaces. It uses your platform account credentials to create payment orders, onboard connected seller accounts, cancel marketplace transactions, and transfer funds between the platform and connected accounts.

## Initialization

```typescript theme={null}
import { Marketplace } from '@nkhind/vivawallet-sdk';

const marketplace = new Marketplace({
  clientId: 'your-smartcheckout-client-id',
  clientSecret: 'your-smartcheckout-client-secret',
  merchantId: 'your-merchant-uuid',
  apikey: 'your-api-key',
  dev: false,
});
```

<ParamField body="clientId" type="string" required>
  Your platform account's OAuth 2.0 Client ID.
</ParamField>

<ParamField body="clientSecret" type="string" required>
  Your platform account's OAuth 2.0 Client Secret.
</ParamField>

<ParamField body="merchantId" type="string" required>
  Your platform merchant UUID, used for Basic Auth endpoints such as payment source management and webhook-key retrieval.
</ParamField>

<ParamField body="apikey" type="string" required>
  Your platform merchant API key, used as the Basic Auth password.
</ParamField>

<ParamField body="sourceCode" type="string">
  Stored on the client and used by the source-code helper when no source code is passed to that helper. Pass source codes in method options when a Marketplace endpoint requires one.
</ParamField>

<ParamField body="dev" type="boolean">
  When `true`, the client uses VivaWallet demo endpoints for API calls.
</ParamField>

## Available Modules

<CardGroup cols={2}>
  <Card title="payments" icon="credit-card">
    Create marketplace payment orders and cancel unpaid orders through the shared payment-order cancellation helper.
  </Card>

  <Card title="sellers" icon="store">
    Create, retrieve, and update connected seller accounts, including payout settings supplied in account payloads.
  </Card>

  <Card title="transactions" icon="arrow-right-arrow-left">
    Retrieve and create transactions through shared transaction helpers, and cancel Marketplace transactions with Marketplace-specific refund options.
  </Card>

  <Card title="transfers" icon="money-bill-transfer">
    Send funds to connected accounts with `sendFunds()` and reverse transfers with `createTransferReversal()`.
  </Card>

  <Card title="webhooks" icon="webhook">
    Manage webhook subscriptions and retrieve the platform account webhook key.
  </Card>

  <Card title="source" icon="code">
    Manage payment source codes for the platform merchant account.
  </Card>
</CardGroup>

### Usage Example

```typescript theme={null}
import { getSmartCheckout } from '@nkhind/vivawallet-sdk';

const orderResult = await marketplace.payments.createOrder({
  amount: 5000,
  customerTrns: 'Purchase from Acme Store',
  customer: {
    email: 'buyer@example.com',
    fullName: 'Alice Buyer',
    requestLang: 'en-GB',
  },
});

if (!orderResult.success) {
  console.error(orderResult.message);
  return;
}

const checkoutUrl = getSmartCheckout({
  orderCode: String(orderResult.data.orderCode),
});
```

After the payment is confirmed, transfer funds to a connected account:

```typescript theme={null}
const transferResult = await marketplace.transfers.sendFunds({
  connectedAccountId: 'connected-account-id',
  amount: 4500,
  transactionId: 'transaction-id-from-webhook-or-lookup',
  description: 'Seller payout for order',
});
```

## How Marketplace Payments Work

In a marketplace flow, payment orders are created under the **platform account**. Once a customer completes payment, your platform distributes funds to connected accounts using the `transfers` module.

```text theme={null}
Customer -> pays -> Platform Account
                      |
             marketplace.transfers.sendFunds()
                      |
              Connected Account
```

A typical flow:

<Steps>
  <Step title="Create a payment order">
    Use `marketplace.payments.createOrder()` to generate an order on the platform account.
  </Step>

  <Step title="Redirect the customer">
    Use `getSmartCheckout()` to build the checkout URL and redirect the customer.
  </Step>

  <Step title="Handle the payment webhook">
    Use the webhook event payload to capture the transaction identifier and reconcile payment state.
  </Step>

  <Step title="Transfer funds to the connected account">
    Call `marketplace.transfers.sendFunds()` with the connected account ID and amount to distribute.
  </Step>

  <Step title="Reverse a transfer if needed">
    Use `marketplace.transfers.createTransferReversal(transferId, options)` when a seller payout must be reversed.
  </Step>
</Steps>

## Related Guides

<CardGroup cols={2}>
  <Card title="Marketplace Payments" icon="credit-card" href="/guides/marketplace-payments">
    Create marketplace payment orders on your platform account.
  </Card>

  <Card title="Marketplace Sellers" icon="store" href="/guides/marketplace-sellers">
    Onboard sellers as connected accounts and configure payout settings.
  </Card>

  <Card title="Marketplace Transfers" icon="money-bill-transfer" href="/guides/marketplace-transfers">
    Send funds to connected accounts and handle reversals.
  </Card>
</CardGroup>