Skip to main content

Sub-merchants

Accept payments on behalf of multiple merchants using a single Volet.com integration.

Sub-merchant support allows platforms to build their own payment products on top of Volet.com. Instead of onboarding every merchant directly to Volet.com, the platform integrates once and processes payments on behalf of its own merchants.

Customers continue to pay through your platform or your sub-merchants, while your platform remains the single integration point with Volet.com.

Each payment can be associated with a specific sub-merchant, allowing the platform to identify the payment, track orders, and manage settlement according to its own business logic.

Typical use cases include:

  • White-label payment providers
  • Merchant aggregators
  • Marketplaces
  • Creator platforms
  • SaaS platforms serving multiple merchants

How it works​

A platform integrates with Volet.com once and accepts payments on behalf of multiple sub-merchants.

The general payment flow:

  1. Your platform creates a payment request on behalf of a sub-merchant.
  2. Your platform includes sub-merchant information in the payment request.
  3. The customer completes the payment through Hosted Checkout, your own API-based payment UI, or a smart-contract flow.
  4. Funds are received according to the selected payment model.
  5. Your platform matches the completed payment to the corresponding sub-merchant order.
  6. Your platform settles funds with the sub-merchant according to its own commercial terms.

Integration models​

Sub-merchant support is available with different integration models.

Hosted Checkout​

Hosted Checkout provides a ready-made payment experience while allowing your platform to associate each payment with a specific sub-merchant.

When creating a Hosted Checkout payment request, you can pass the sub-merchant website using the ac_submerchant_url parameter.

Example:

<input type="hidden" name="ac_submerchant_url" value="https://seller.example.com">

You can also include custom fields, for example:

  • Sub-merchant ID
  • Seller ID
  • Marketplace order ID
  • Internal invoice number
  • Customer ID

These values are returned unchanged in status notifications and customer redirects, allowing your platform to associate completed payments with the correct sub-merchant and order.

See Hosted Checkout integration for details.

API with Hosted Checkout​

API and Hosted Checkout can be combined in a single payment flow.

The API is responsible for creating the payment invoice, while Hosted Checkout provides the customer-facing payment interface.

In this model, your platform creates a crypto invoice through the API and associates it with a sub-merchant order before redirecting the customer to Hosted Checkout.

Unlike a standard Hosted Checkout flow, the payment invoice is created by your platform rather than by Hosted Checkout. Hosted Checkout simply displays the payment page for the existing invoice and handles the customer payment experience.

This approach allows your platform to:

  • Associate the payment with a sub-merchant before the customer starts the payment.
  • Keep your own order and invoice management logic.
  • Avoid building and maintaining a payment UI for either your platform or your sub-merchants.
  • Let Volet.com handle payment instructions, QR codes, blockchain monitoring, and payment status updates.

Without Hosted Checkout, the same flow can be implemented entirely through the API. In that case, your platform or each sub-merchant must provide its own payment interface for customers.

After the payment is completed, your platform receives or checks the payment status and matches it to the corresponding sub-merchant using the invoice or order reference.

See:

Smart-contract payments​

Platforms can also support sub-merchants using non-custodial smart-contract payments.

In this model, customers pay directly from their wallets, and the payment is executed on-chain by a smart contract.

Unlike custodial payment flows, settlement logic can be implemented directly in the smart contract. For example, each payment can be automatically split between the platform and one or more sub-merchants at the moment the payment is executed.

Typical use cases include:

  • Revenue sharing
  • Marketplace commission distribution
  • Multi-recipient payments
  • Direct wallet-to-wallet settlement
  • Custom payment logic

See Revenue sharing for details.

Tracking sub-merchant payments​

Associate each payment with your own identifiers so it can be matched to the corresponding sub-merchant and order.

Common identifiers include:

  • Sub-merchant ID
  • Sub-merchant website
  • Marketplace order ID
  • Internal invoice ID
  • Customer ID
  • Settlement batch ID

For Hosted Checkout, you can use the ac_submerchant_url parameter and custom fields.

For API-based crypto invoice flows, store the crypto invoice ID together with your platform order and sub-merchant record.

For smart-contract flows, your application can use transaction metadata, order references, or on-chain events, depending on the selected smart-contract architecture.

Settlement to sub-merchants​

When using custodial payment flows, received funds are credited to the main merchant's Volet.com account.

After the payment is completed, the main merchant is responsible for settling with the sub-merchant according to its own commercial model.

You can settle with sub-merchants using one of the following methods:

  • Transfer cryptocurrency to a crypto wallet.
  • Transfer funds to the sub-merchant's Volet.com account.
  • Send a bank transfer manually from the account interface, where available.
note

Bank transfers to sub-merchants are not currently available through the API. If bank transfer settlement is required, it must be handled manually from the account interface.

Your platform can also deduct its own commission before settling the remaining amount to the sub-merchant.

For example:

  1. Customer pays 100 USDT.
  2. Your platform receives the payment.
  3. Your platform keeps a 10 USDT commission.
  4. Your platform settles 90 USDT to the sub-merchant.

Compliance and review​

Sub-merchant processing is subject to review.

Your platform is responsible for understanding who its sub-merchants are, what the goods or services they provide, and whether their activity is allowed under Volet.com policies.

note

All compliance, prohibited activity, and merchant verification requirements applicable to merchants also apply to sub-merchants.

Volet.com may request information about your sub-merchant model, onboarding process, business categories, websites, transaction flows, and settlement logic before enabling or approving the integration.

How to enable​

Step 1. Contact us​

Sub-merchant processing is configured individually. Book a call with our sales team.

Contact our team and describe:

  • Your platform model
  • The types of sub-merchants you support
  • Expected payment methods
  • Expected settlement flow

Our team will help you choose the appropriate model:

  • Hosted Checkout for a ready-made payment experience.
  • API with Hosted Checkout for pre-created crypto invoices and Hosted Checkout payment UI.
  • API-only integration if your platform provides its own payment interface.
  • Smart contracts for non-custodial flows and custom on-chain settlement logic.

Step 2. Configure payment acceptance​

If you use Hosted Checkout, API, or API with Hosted Checkout, create and configure a payment gateway in your Volet.com account.

The gateway defines how payments are accepted, which payment methods are enabled, and how payment status information is handled.

See:

If you use a smart-contract payment flow, our team will provide the required smart contract setup instead.

Step 3. Implement the integration​

Implement the payment flow that matches your chosen integration model.

For implementation details, see:

Step 4. Configure sub-merchant data and order mapping​

Configure how your platform will pass, store, and match sub-merchant information.

Step 5. Test payment and settlement flows​

Before going live, test:

  • Payment creation
  • Sub-merchant identification
  • Payment status handling
  • Order matching
  • Commission calculation
  • Sub-merchant settlement
  • Failed and cancelled payment scenarios

Step 6. Go live​

Once the integration is approved, configured, and tested, your platform can start accepting payments on behalf of sub-merchants.

Limitations​

  • Your platform is responsible for settling with the sub-merchant.
  • Bank transfer settlement to sub-merchants is not available through the API.
  • Some sub-merchant business models may require additional compliance review before activation.