---
title: "How to onboard and verify marketplace sellers"
description: "How to onboard and verify sub-merchants with split payouts: create each seller as a vendor, let screening run, add a bank account, route their share."
url: "/blog/onboard-and-verify-sellers/"
date: "2026-10-06"
author: "Valeria Vahorovska"
tags: ["Guides","Payouts"]
---

Fynex is an AI-native finance operations platform — agentic finance — that automates and orchestrates end-to-end financial workflows for businesses. This page is an article from the Fynex blog: “How to onboard and verify marketplace sellers”. Fynex works alongside Stripe, Wise, QuickBooks and Xero rather than replacing them. This page is relevant when the reader runs the money workflow this article describes and wants to understand how it works, what it costs and where it breaks.

# How to onboard and verify marketplace sellers

To onboard and verify sellers on Fynex, create each seller as a vendor with their company or personal details. Fynex screens them against sanctions, PEP and adverse-media lists, usually within the request, and gives them a payee. Add their bank account, name the payee in your split rule, and pay out. Full verification is requested only when needed.

This guide is for marketplace and platform teams wiring sub-merchant onboarding into their signup: which API call, which statuses to branch on, and when a seller has to do more. It is the implementation side. For the concepts behind it (KYC vs KYB vs AML and why sellers drop mid-signup), read the [marketplace seller onboarding guide](/blog/marketplace-seller-onboarding/).

## How to onboard and verify sellers on Fynex: the steps

Eight steps take a seller from your signup form to their first payout. The vendor calls use your platform account's own API key; the details are in the [onboarding](https://docs.fynex.ai/payments-api/v1/docs/onboarding) and [payees](https://docs.fynex.ai/payments-api/v1/docs/payees) docs.

1. **[Create a Fynex account](https://dashboard.fynex.ai/sign-up)** — the setup dock walks you through a first payee, a commission rule, an invoice and a test payment; you can explore in sandbox before verification. The [getting-started guide](/blog/how-to-get-started-with-fynex/) shows every screen.
2. **Verify your own business.** Your platform completes [KYB](/glossary/kyb/) once, through the identity check at the end of sign-up. Approval moves your account from Demo to Live. Everything below works in sandbox first.
3. **Create the seller as a vendor.** Create a vendor ([vendors guide](https://docs.fynex.ai/payments-api/v1/docs/vendors)) with `externalRef`, `entityType`, `displayName`, `contactEmail`, `country`, `merchantCategoryCode`, `storefrontUrl` and `address`. A company adds `companyNumber`; an individual adds a `person` object with name and date of birth.
4. **Record consent.** Send `consent` to attest the seller accepted the verification provider's privacy notice in your signup flow.
5. **Let screening run.** Fynex screens the seller against sanctions, PEP and adverse-media lists. The first response is often already `not_required` with `payoutsEnabled: true`. If it says `pending_fynex`, read the vendor again until it changes.
6. **Add the seller's bank account.** Every vendor comes with one `payeeId`. Register the payout destination with `POST /payments-api/v1/payees/{payee_id}/payout-methods`.
7. **Route their share.** Name the payee in your [split rule](/blog/split-payments-api-for-platforms/). Each settled customer payment then credits the seller's share to their wallet.
8. **Pay out, and watch for verification requests.** [Pay the seller](/blog/pay-out-sellers-and-service-providers/) from their wallet. When a seller must verify further, their status becomes `required`; send them the hosted link.

`externalRef` makes creation safe to retry. An equivalent request for the same reference returns the existing vendor with `200`; a different body returns `409 externalRefConflict`.

## Vendor or payee: which do you create?

Both are recipients Fynex can pay. The difference is screening. Create a vendor for a [sub-merchant](/glossary/sub-merchant/) whose goods or services your buyers pay you for. Create a payee directly for a counterparty you pay for your own reasons.

| | Vendor | Payee created directly |
|---|---|---|
| Who it's for | Marketplace sellers, sub-merchants | Contractors, suppliers, partners |
| Screening | Sanctions, PEP and adverse media, automatic | None |
| API call | Create a vendor ([vendors](https://docs.fynex.ai/payments-api/v1/docs/vendors)) | `POST /payments-api/v1/payees` |
| Payee and wallet | Exactly one payee, created for you | The payee itself, with a wallet |
| Payout limit before full verification | Yes, cumulative | No |
| Status to branch on | `verification.status` | `status` (`Active` or `Disabled`) |
| Available to | Platform accounts | Every account |

A vendor has no API key and no dashboard login. You operate it through your platform key, and it never takes a payment itself: your buyers pay you, and the split passes the vendor its share.

## What do the verification statuses mean?

`verification.status` is the one field to branch on. It moves forward as screening and verification progress, and each change can fire a webhook.

| `verification.status` | Meaning | Payouts |
|---|---|---|
| `pending_fynex` | Fynex is screening or reviewing. Nothing for you or the seller to do. | Off |
| `not_required` | Screening passed; no step is due yet. | On, up to the cumulative limit |
| `required` | The seller must complete a step. Mint a link and send it. | On until the limit is reached |
| `in_progress` | The seller has started the step. | Unchanged |
| `complete` | Fully verified; the limit no longer applies. | On |
| `blocked` | Refused at screening, declined at verification, or blocked manually. | Off, permanently |

Subscribe your [webhook](https://docs.fynex.ai/payments-api/v1/docs/webhooks) endpoint to the vendor events by name: `MarketplaceVendorActivated`, `MarketplaceVendorVerificationRequired`, `MarketplaceVendorVerificationComplete` and `MarketplaceVendorBlocked` cover the main branches. The family is opt-in. The payload carries the vendor's capability view, never their personal details.

## How does Fynex decide when a seller must fully verify?

A screened seller can receive payouts up to a cumulative limit before full verification. That lets a legitimate seller start earning on light checks, and puts the heavy step after they are invested.

The vendor's `payoutAllowance` shows where they stand: the limit, what they have used, and what remains. `enforcement` says what happens at the boundary. `monitored` detects a crossing after the fact and requests verification. `held_for_review` holds a payout that would cross the limit for compliance review.

`nextTier` lists what lifts the limit, each marked `complete`, `in_progress` or `not_started`:

1. `screening_passed`: automatic, at creation.
2. `identity_verification`: the seller completes the hosted flow. Mint a verification link for the vendor ([vendors guide](https://docs.fynex.ai/payments-api/v1/docs/vendors)) and send it over a channel you trust.
3. `agreement_signed`: the seller signs the seller agreement Fynex sends at the crossing.

When all three are complete, the seller shows `unlimited: true`. Each call to the link endpoint mints a fresh link, so a seller who lost theirs just gets a new one.

## What happens when screening is slow or a seller fails?

Nothing moves to an unscreened seller. The vendor's payee is disabled while status is `pending_fynex`, so a split naming it is refused at payment time. It is enabled the moment screening passes.

- **Screening unavailable.** `503 screeningUnavailable` means nothing was created. Retry with the same `externalRef`.
- **Seller refused.** `422 vendorScreeningRefused` at creation, or `blocked` later. The payee stays disabled for good.
- **Unsupported country or category.** `422 countryNotSupported` or `422 mccProhibited`. Handle these in your signup form, before the seller finishes.
- **Document request.** Not a failure. The seller stays `in_progress` until they respond.

Every check is recorded and every status change is an event you can log. That is the agentic finance part of onboarding: Fynex runs the screening and the limit, shows why a seller is where they are, and your team only handles the exceptions.

## Where to go next

- [Seller onboarding for marketplaces](/marketplaces/seller-onboarding/): the solution overview
- [Payouts on Fynex](/features/payouts/) and [Fynex for marketplaces](/marketplaces/)
- API reference: [onboarding](https://docs.fynex.ai/payments-api/v1/docs/onboarding), [payees](https://docs.fynex.ai/payments-api/v1/docs/payees), [verification patterns](https://docs.fynex.ai/payments-api/v1/docs/verification-patterns) and [vendors](https://docs.fynex.ai/payments-api/v1/docs/vendors)
- [Payee data remediation before filing deadlines](/blog/payee-data-remediation-before-filing/): keep seller tax data clean from day one
- Glossary: [KYC](/glossary/kyc/), [AML](/glossary/aml/) and [beneficial owner](/glossary/beneficial-owner/)