Seller Verification API for Marketplaces: A Trust Ladder

Key takeaways

• Use a trust ladder: browse and draft listings with almost no checks, list products after a PAN check, receive payouts after a bank-account check, and grant higher limits after registration checks (GSTIN, CIN or Udyam) for the sellers that need them.
• Tie verification to money movement, not to signup. The payout step is where a wrong or fraudulent account actually hurts, so gate payouts on a verified account in the seller's name.
• A PAN can sit behind several GSTINs in different states. pan-to-gstin lists them, so you can confirm the seller's chosen registration is real and active without asking for screenshots.
• Detect linked accounts by storing a keyed hash of the PAN and the account number, so that the same person opening five stores is visible without keeping raw identifiers lying around.
• Name differences between brand, store and legal name are normal. Decide which name each check compares, and give sellers messages that tell them exactly what to fix.
• valid: false and found: false are completed, billable calls. Only retry 429 and 502.
• Cost per seller is small next to the cost of one bad payout. The arithmetic for three seller volumes is below, from the published rate card.

Why marketplaces verify sellers, in plain terms

The need shows up as four recurring problems.

Fake or duplicate sellers. Someone opens many accounts with variations of the same details to evade a ban, to game ratings or to dodge limits.

Payout fraud. The account details on a seller profile are changed shortly before a large payout, or the account never belonged to the seller in the first place.

Tax and invoice questions. Marketplaces handle seller tax details for invoices, and an invalid or cancelled registration on a seller who must charge tax becomes your support and compliance problem. The exact obligations of an e-commerce operator, such as registration of sellers and collection of tax at source, are matters for your tax adviser; the engineering point is that you want accurate registration data on file.

Misrepresentation. A seller claims to be a registered company, an MSME or an authorised dealer. Some claims you can verify against a registry and some you cannot; knowing which is which keeps your badges honest.

The seller trust ladder

The table sets out what a seller can do at each rung and what you ask for in return. The limits in the right-hand column are placeholders to tune with your risk team.

Two properties make the ladder work. A tier is only granted when the evidence for it is complete, and a tier can be removed when new evidence contradicts it, for example when a GST registration is later cancelled. And the cost scales with success: sellers who never reach tier 2 never trigger a bank-account call.

What each type of seller brings

Not every seller brings the same identifiers, and your form should adapt.

• Individual selling under their own name. A PAN of type individual, a personal account. Tier 3 may not apply at all.
• Sole proprietor with a shop name. An individual's PAN, an account in the proprietor's name, perhaps a GSTIN with the proprietor as legal name and the shop as trade name.
• Partnership firm or LLP. The firm's PAN, an account in the firm's name, a GSTIN if registered. There is no CIN lookup for an LLP on this platform, so rely on PAN, GSTIN and bank checks plus documents.
• Company. The company's PAN, a CIN, a GSTIN, a current account.
• Micro or small enterprise. Any of the above plus a Udyam number if the seller claims MSME status.
• Gig or delivery partner. An individual with a driving licence and, if the vehicle is theirs, a vehicle registration. These use verify/driving-license and verify/rc, covered below.

The workflow, step by step

1. Verify the contact. Send an OTP to the mobile number and confirm the email, using your own provider. Decision: no verified contact, no account. This is not a StampMitra call.
2. Collect the legal name and PAN on one screen. Say clearly that the name must match the PAN. Validate the pattern locally: ten characters, the right letter positions. Decision: correct the field or continue.
3. Verify PAN (tier 1). POST /v1/verify/pan with pan and name. Read valid, type, registeredName, nameMatchResult and nameMatchScore. Decision: continue on a strong match; ask once for a corrected name on a weak one; reject on valid: false after one re-entry; route a type that contradicts what the seller said to review.
4. Check for duplicates. Compute a keyed hash of the PAN and look it up in your seller table. Decision: if the hash already exists on another account, apply your duplicate policy (merge, block, or review) before spending anything more.
5. Collect payout details at the first payout, not at signup. Ask for the account number and IFSC when the seller first has money waiting, which puts the ask at the moment of motivation.
6. Verify the bank account (tier 2). POST /v1/verify/bank-account with accountNumber, ifsc and the legal name. Decision: release payouts only for a valid account with a strong name score; send a middling score to review; ask for another account if the account is not valid.
7. Collect the GSTIN where it applies. Check the pattern and that the PAN inside it equals the verified PAN, which is free.
8. Verify the registration (tier 3). POST /v1/verify/gstin and, for sellers with registrations in several states, POST /v1/verify/pan-to-gstin. Decision: active registration whose PAN matches, grant tier 3; otherwise hold at tier 2 and tell the seller what to fix.
9. Verify the entity when the seller says it is a company or an MSME. verify/cin, verify/udyam. Decision: badges only for what the registry confirmed.
10. Record the evidence and the tier. Store referenceId, time, key response fields, decision and the rule version for each check, linked to the seller.
11. Schedule re-checks. Re-verify registration status for tier 3 sellers on a schedule and on trigger events.

Sample request and response: one PAN, several GSTINs

Sellers who operate in more than one state hold more than one GSTIN under the same PAN. Instead of trusting a typed GSTIN, resolve the list from the verified PAN:

curl -X POST "https://api-b2b.stampmitra.in/v1/verify/pan-to-gstin" \
  -H "Authorization: Bearer $STAMPMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pan":"ABCDE1234F"}'

{
  "referenceId": "SMV-20260927-1L67Z5",
  "found": true,
  "gstins": [
    { "gstin": "07AAAAA1111A1Z1", "state": "Delhi", "status": "Active" }
  ]
}

A Node function turns the list into a decision. If the seller has picked a GSTIN, confirm that it is in the list and active; if they have not, offer the list.

const BASE = "https://api-b2b.stampmitra.in";

export async function resolveSellerGstin(verifiedPan, chosenGstin) {
  const res = await fetch(`${BASE}/v1/verify/pan-to-gstin`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STAMPMITRA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ pan: verifiedPan }),
  });
  if (res.status === 429 || res.status === 502) return { outcome: "retry_later" };
  if (res.status === 402) return { outcome: "ops_alert" };
  const body = await res.json();
  if (!res.ok) return { outcome: "fix_input", requestId: body.error?.requestId };
  if (!body.found || !body.gstins?.length) return { outcome: "no_registration", ref: body.referenceId };

  const active = body.gstins.filter((g) => String(g.status).toLowerCase() === "active");
  if (chosenGstin) {
    const hit = body.gstins.find((g) => g.gstin === chosenGstin);
    if (!hit) return { outcome: "not_linked_to_pan", ref: body.referenceId };
    if (String(hit.status).toLowerCase() !== "active") return { outcome: "inactive", state: hit.state, ref: body.referenceId };
    return { outcome: "confirmed", state: hit.state, ref: body.referenceId };
  }
  return { outcome: "choose", options: active.map((g) => ({ gstin: g.gstin, state: g.state })), ref: body.referenceId };
}

Decision table: valid, mismatch, inactive, not found

Linked accounts and duplicate sellers

Banning a bad seller only works if they cannot return under a new email. The strongest signals you can compute from verification data are the PAN and the bank account. Do not store them in plain form in your seller table. Instead store a keyed hash (an HMAC with a secret kept in your key management system) of each, and compare hashes. That lets you ask "does another seller use this PAN?" and "does this account appear on another seller?" without a column of raw identifiers that a breach would expose.

import hmac, hashlib, os

SECRET = os.environ["SELLER_HASH_KEY"].encode()

def keyed_hash(value: str) -> str:
    normalised = "".join(value.split()).upper()
    return hmac.new(SECRET, normalised.encode(), hashlib.sha256).hexdigest()

def duplicate_policy(pan_hash: str, account_hash: str, seller_id: str, repo) -> str:
    same_pan = repo.sellers_with_pan_hash(pan_hash, exclude=seller_id)
    same_account = repo.sellers_with_account_hash(account_hash, exclude=seller_id)
    if same_account:
        return "review_shared_account"
    if same_pan:
        return "review_second_store"
    return "ok"

A shared PAN is not always fraud. A genuine seller may open a second store for a different category, and a family business may share an account. The point of the hash is to surface the pattern to a reviewer, not to auto-ban.

Gating payouts

The payout is where verification earns its keep, so build the gate in the payout service, not in the seller UI where a client bug could bypass it. The gate should require a verified account for the seller, a name score above your threshold or a reviewer's approval, an account that has not changed in the cooling-off window, and a seller tier that permits the amount. Every change of payout account restarts the verification and the cooling-off period, and notifies the seller on their verified mobile and email so that an account takeover is visible to them.

Hold the first payout for a short, fixed period after the first sale if your risk team wants a chargeback buffer. That is a business rule, not a verification result, but it makes sense to keep it in the same gate.

Make the gate explainable. When it refuses a payout, it should return a reason code that the seller-support screen can translate into plain words: account not verified, name mismatch under review, cooling-off after a change, tier cap reached. Support agents who can see the reason resolve most tickets in one reply, and analysts who can see the reason spot a rule that is firing too often. A gate that only says "blocked" produces escalations, not resolutions.

Delivery partners and drivers: licence and vehicle checks

Platforms that onboard drivers or delivery riders need different documents. The driving-licence endpoint, POST /v1/verify/driving-license, takes dlNumber and dob and returns the holder's name, the validity date and the licence status. The vehicle endpoint, POST /v1/verify/rc, takes vehicleNumber and returns owner name, registration status, rcStatus, expiry and insurance date, and whether the vehicle is commercial. Both are sensitive scopes: expect to use an IP-allowlisted production key, and note that the RC endpoint is in the premium price band.

Decisions follow the same pattern. A licence whose status is not active or whose validity has passed is a stop. A vehicle whose owner is not the rider needs a document explaining the relationship, such as an authorisation from the owner, which is a review case. A commercial or private classification that does not fit the service is a policy question. As always, these checks confirm records, not driving skill or safety, and the decision on whom to engage stays with you.

Seller messages that help instead of leak

The words you show a seller when a check fails matter. Say what to fix, not what the registry said. "The legal name must match your PAN exactly as printed" is more useful and safer than echoing the registered name back, which would let someone probe for other people's names by guessing PANs. Do not reveal whether a PAN exists on another account. For payouts, say "we could not match this account to your name" and ask for a different account or a document, rather than showing the name at the bank. Show a reference you can look up, such as your own case id, never the raw upstream response.

Five scenarios from the trust-and-safety desk

These are hypothetical cases that show the ladder in motion.

The quick first sale

A seller registers, verifies the mobile number, enters PAN and name, and lists ten products within minutes. The PAN check is the only paid call so far. A day later a first order arrives, the seller adds an account, and the bank check returns a valid account with a strong match. Payouts start after the holding period.

The second store

A new seller's PAN hash matches an existing seller who was suspended for counterfeit complaints. The duplicate policy routes the account to review, and the reviewer sees the first store's history and the reason for suspension. The second account is declined. No further verification calls are spent.

The multi-state brand

A seller selling in three states types one GSTIN. The PAN-to-GSTIN lookup shows three registrations, two active and one cancelled. The system offers the two active ones for pickup locations and notes the cancelled one in the seller's compliance panel. Tier 3 is granted for the active states only.

The payout account swap

A seller with a long history changes the payout account the day before a large settlement. The new account verifies as valid but the name at the bank is a different person. The change is held, the settlement goes to the old verified account, the seller is notified on the verified mobile number, and the case goes to review.

The registry outage

During a sale event, the PAN call returns 502 for a few minutes. New sellers are placed in a "verification pending" state with a clear message and keep drafting listings. Retries with backoff pick them up when the source recovers. Nobody is approved by default and nobody is rejected for a platform error.

Appeals and seller disputes

A verification system that can say no needs a way to hear "you are wrong". Source records are sometimes out of date, names are sometimes spelled differently across registries, and a seller can be blocked by a typing slip on your own form. Build an appeal path before the first rejection goes out.

Give every rejection a case id that the seller can quote and that your analysts can search. Tell the seller which step failed (PAN, account, registration) and what would resolve it, without echoing the source data. Let the seller re-enter a field once without opening a case, because most failures are typos. For anything beyond that, accept a document upload, and have a human compare it with the declared values. If the document shows that the source record is stale, record that conclusion on the seller's file and the reviewer's name, and grant the tier by manual override with a second approver. Never loop the API in the hope that the answer changes: a repeated negative is billed again and returns the same result.

Track the outcome of appeals. If a large share of appeals on one rule succeed, the rule is too strict. If almost none do, the rule might be fine, or sellers might have stopped appealing. Look at the abandonment rate on the rejection screen to tell which.

Patterns that differ by marketplace type

The ladder is generic, but the hot spots move depending on what you sell.

Goods marketplaces care most about registration status and duplicate stores. Counterfeit and abandoned-listing problems tend to come from accounts that were created in bulk, so the duplicate hash and the PAN-to-GSTIN check carry more weight than they do elsewhere.

Services and freelancer marketplaces often deal with individuals who are not GST-registered. For them tier 3 may never apply, and the PAN plus bank-account pair is the whole story. Use tier 4 manual review for categories with elevated risk and for any seller whose payout volume grows quickly.

Quick-commerce and delivery platforms onboard riders and store partners at high volume. The licence and vehicle checks matter for riders, and the store partner is a business with the registration checks. Throughput and turnaround matter most, so keep the review queue short and measure it daily.

B2B marketplaces sell to businesses that want tax invoices and credit terms. Buyers will ask whether a supplier's registration is genuine, so the registration checks and the status re-checks carry the trust. The KYB guide for B2B platforms goes further into entity checks for this case.

Cross-border or export sellers may not have Indian registrations at all. Route them through a separate flow and do not force Indian identifiers on sellers who do not hold them.

Review rules a marketplace can copy

These are suggestions for your risk and policy teams to adapt.

• Tier 1 needs a valid PAN of a type that fits the seller's declared kind, and a name score above your high threshold or a reviewer's approval.
• Tier 2 needs a valid account in the seller's name. Name scores in the middle band go to review, and low scores are held.
• Tier 3 needs an active registration whose PAN equals the verified PAN. A badge that mentions a registration appears only for what a registry confirmed.
• Escalate when a PAN hash or account hash appears on more than one seller, when an account changes within a short time of a large settlement, or when a seller's registration status turns inactive.
• Two approvers for restoring a seller who was suspended, and for any manual tier upgrade.
• Cooling-off after any payout account change, and a notification on the verified mobile and email.
• Do not auto-ban on a single signal. Use signals to route to review, and keep the decision with a person for anything that ends a seller's business.

Operating model

Run three queues. The onboarding queue handles name mismatches and unresolved registrations, with a turnaround target of one business day as a starting suggestion. The payout-hold queue handles account mismatches and changes, with a shorter target because sellers are waiting for money. The risk queue handles duplicate and linked-account cases and escalations, staffed by senior trust-and-safety analysts. Measure the age of the oldest item in each queue and keep it visible.

Give analysts a single screen per seller showing the declared values and the verified values side by side, the referenceId of each check, the tier history and the notes. Do not make them copy values between systems.

What to store and for how long

Per check, store the product, referenceId, time, the environment of the key, a masked or hashed form of the identifier, the response fields you used, the decision, the rule version and the reviewer. Keep raw PANs, account numbers and licence numbers out of application logs. Separate operational data from the evidence archive and apply access control and audit to both.

How long to retain seller records depends on tax and accounting rules, consumer and e-commerce rules, your contracts, and data-protection law for the personal data of individual sellers. We cannot give you the periods. Take the question to your counsel, write the answer into a retention schedule, and automate it. StampMitra's own handling is described in its retention and deletion schedule and data processing addendum.

What it costs: three seller volumes

Pay-as-you-go prices are ₹5 per call for PAN, GSTIN, CIN, Udyam and the cross-lookups, and ₹4 for the bank-account check; the premium band for licence and RC checks is ₹9 on pay as you go. Growth and Scale lower the standard and premium rates and add a monthly plan fee, and the bank-account rate is the same on all plans. All amounts exclude GST at 18%.

For one seller at tier 2 (PAN plus bank account), and for one seller at tier 3 (adding a GSTIN):

Monthly models need an assumption about the funnel. We assume every new seller gets a PAN check, all of them reach the bank check eventually in this model, and 40 percent of sellers also get a GSTIN check. Replace the percentages with your own. At 1,000 new sellers a month that is 1,000 PAN and 400 GSTIN calls (1,400 standard calls) and 1,000 bank checks.

At 10,000 new sellers a month: 14,000 standard calls and 10,000 bank checks.

At 100,000 new sellers a month, as a very large platform might see: 140,000 standard calls and 100,000 bank checks.

Three observations. At small volume the plan fees outweigh the lower rates, so pay as you go or Growth is the economical choice. As the seller base grows, Scale overtakes Growth. At the largest level, monthly spend is well above the level at which StampMitra suggests enterprise arrangements, and that is a commercial conversation via the contact page. The tables assume GST applies to plan fees too, which you should confirm on an invoice. Usage is recorded after a successful response, so calls that return an error are not charged, but valid: false is a successful call. Staging the ladder keeps the bank check and the registry checks for sellers who actually reach those rungs, so the real monthly cost is often below the all-sellers-reach-everything model above.

Rollout: sandbox, pilot, production

Sandbox. Build the ladder against sandbox keys, where responses are sample data and no wallet is debited. The sandbox responder returns a valid result for the PAN SNDBX0000A and an invalid one for SNDBX9999F, and for GSTIN the pair 09SNDBX0000A1Z5 and 09SNDBX9999F1Z5; other inputs give stable but arbitrary outcomes, so do not assert on them. Confirm the current test values in the dashboard. Test each tier transition, tier removal, the duplicate policy, the payout gate and the 402, 429 and 502 paths.

Pilot. Apply for production access, which needs your organisation's KYC approval and the per-product application. Turn on the ladder for new sellers in one category or city while keeping your existing review process in parallel, and compare decisions.

Production. Extend the ladder category by category, then consider back-verifying existing sellers in tier order, with the highest payout volume first. Keep an alert on wallet balance, and use the sandbox versus production keys guide for key scopes and the IP allowlist.

Metrics worth watching

• Signup to tier 1, tier 1 to tier 2, and tier 2 to tier 3 conversion. A cliff at one step tells you which ask is too heavy.
• Share of sellers in the review band and the age of the oldest item.
• Payout holds by reason, and how many were released after review.
• Duplicate-hash hits, and the share that reviewers confirmed as the same operator.
• Payout-account changes per thousand sellers, and the share held.
• Sellers whose registration status became inactive, and what happened next.
• Verification cost per seller who reached tier 2, not per signup.

Mistakes that weaken seller verification

• Verifying everything at signup. It loses honest sellers and spends money on people who never sell.
• Gating in the UI only. A client bug or a direct API call bypasses it. Gate in the payout service.
• Storing raw identifiers for duplicate detection. Use keyed hashes.
• Treating the brand name as the legal name. Decide which name each check compares.
• Echoing registry data back to sellers. It leaks other people's information to anyone guessing numbers.
• Ignoring status changes. A registration or licence that was active at tier-up may not be active later.
• Auto-banning on one signal. Use signals to route to people.
• Copying sandbox behaviour into production. Sandbox data is synthetic. Revalidate with a small production cohort.

Related APIs and guides

The endpoints on this page are in the verification API reference: PAN, bank account, GSTIN, PAN to GSTIN, driving licence and vehicle RC. For more, read the vendor onboarding verification page, which covers supplier-side checks, bank account verification before payout, the KYB guide for B2B platforms, the business verification guide and the errors guide. All industry pages are listed on the solutions page, and current rates are on the pricing page.

API reference at a glance

{
  "referenceId": "SMV-20260927-8F42K7",
  "pan": "ABCDE1234F",
  "type": "Individual",
  "valid": true,
  "registeredName": "RAHUL KUMAR",
  "fatherName": "SURESH KUMAR",
  "panStatus": "VALID",
  "panStatusCode": "E",
  "panStatusDescription": "Existing and valid PAN",
  "nameMatchResult": "MATCH",
  "nameMatchScore": "100",
  "aadhaarSeedingStatus": "y",
  "aadhaarSeedingStatusDescription": "Aadhaar linked",
  "lastUpdatedAt": "2023-04-01",
  "message": "PAN is Valid"
}

{
  "referenceId": "SMV-20260927-1L67Z5",
  "found": true,
  "gstins": [
    {
      "gstin": "07AAAAA1111A1Z1",
      "state": "Delhi",
      "status": "Active"
    }
  ]
}

{
  "referenceId": "SMV-20260927-3B71A0",
  "valid": true,
  "nameAtBank": "RAVI KUMAR",
  "bankName": "ICICI Bank",
  "utr": "017952100012345",
  "city": "Mumbai",
  "branch": "Andheri West",
  "micr": "400229002",
  "nameMatchScore": "100",
  "nameMatchResult": "GOOD_MATCH",
  "accountStatus": "ACCOUNT_IS_VALID",
  "accountStatusCode": "1",
  "ifscDetails": {
    "bank": "ICICI Bank",
    "ifsc": "ICIC0001234",
    "micr": "400229002",
    "address": "Andheri West, Mumbai",
    "city": "Mumbai",
    "state": "Maharashtra",
    "branch": "Andheri West"
  }
}

Frequently asked questions