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

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,
});

clientId · string · required

Your platform account’s OAuth 2.0 Client ID.

clientSecret · string · required

Your platform account’s OAuth 2.0 Client Secret.

merchantId · string · required

Your platform merchant UUID, used for Basic Auth endpoints such as payment source management and webhook-key retrieval.

apikey · string · required

Your platform merchant API key, used as the Basic Auth password.

sourceCode · 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.

dev · boolean

When true, the client uses VivaWallet demo endpoints for API calls.

Available Modules

payments

Create marketplace payment orders and cancel unpaid orders through the shared payment-order cancellation helper.

sellers

Create, retrieve, and update connected seller accounts, including payout settings supplied in account payloads.

transactions

Retrieve and create transactions through shared transaction helpers, and cancel Marketplace transactions with Marketplace-specific refund options.

transfers

Send funds to connected accounts with sendFunds() and reverse transfers with createTransferReversal().

webhooks

Manage webhook subscriptions and retrieve the platform account webhook key.

source

Manage payment source codes for the platform merchant account.

Usage Example

import { getSmartCheckout } from '@nkhind/vivawallet-sdk';

const orderResult = await marketplace.payments.createOrder({
  amount: 5000,
  customerTrns: 'Purchase from Acme Store',
  customer: {
    email: '[e-mail]',
    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:

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.

Customer -> pays -> Platform Account
                      |
             marketplace.transfers.sendFunds()
                      |
              Connected Account

A typical flow:

1. Create a payment order

   Use marketplace.payments.createOrder() to generate an order on the platform account.

2. Redirect the customer

   Use getSmartCheckout() to build the checkout URL and redirect the customer.

3. Handle the payment webhook

   Use the webhook event payload to capture the transaction identifier and reconcile payment state.

4. Transfer funds to the connected account

   Call marketplace.transfers.sendFunds() with the connected account ID and amount to distribute.

5. Reverse a transfer if needed

   Use marketplace.transfers.createTransferReversal(transferId, options) when a seller payout must be reversed.

Related Guides

Marketplace Payments

Create marketplace payment orders on your platform account.

Marketplace Sellers

Onboard sellers as connected accounts and configure payout settings.

Marketplace Transfers

Send funds to connected accounts and handle reversals.