Marketplace (Sub-contas) - Visão Geral

#Introdução

O recurso de Marketplace permite que a sua conta opere como uma plataforma: você cadastra sub-contas (os vendedores que vendem por meio de você), acompanha o credenciamento de cada uma, define quanto a plataforma leva em cada venda e cobra em nome delas. É o modelo "Connect": cada sub-conta é um vendedor com cadastro, saldo e saques próprios, e a plataforma recebe a sua parte automaticamente.

O recurso é habilitado por conta. A Selectwin liga a função para a sua conta e a submete a uma aprovação de compliance; só depois disso a API aceita criar sub-contas. Consulte o estado com GET /v1/marketplace.

#Conceito e Funcionalidade

Uma sub-conta nasce com o status pending e passa pelo mesmo credenciamento (KYC) de qualquer conta Selectwin. Há dois caminhos para completá-lo:

• Link de credenciamento: você gera um link secreto para a sub-conta e o envia ao vendedor; ele preenche os dados e documentos numa página hospedada pela Selectwin, sem precisar de login. Veja Link de credenciamento.
• Pelo painel: quem tem acesso à plataforma alterna para a sub-conta e preenche o cadastro.

Enquanto a sub-conta não está active, ela não cobra nem saca. Assim que é aprovada, você passa a cobrar em nome dela com onBehalfOf em Transações e em Sessões de checkout, e a plataforma recolhe a sua taxa como um split adicional.

A taxa da plataforma é definida de uma de duas formas, por sub-conta:

Uma sub-conta usa uma das duas (nunca ambas). Sem nenhuma, a plataforma não recolhe taxa nas vendas dela.

#Fluxo típico

1. GET /v1/marketplace — confirme enabled: true e approvalStatus: "approved".
2. POST /v1/marketplace/sub-accounts — crie a sub-conta com o nome do vendedor e a taxa (ou o plano).
3. POST /v1/marketplace/sub-accounts/{companyId}/kyc-link — gere o link e envie ao vendedor.
4. Acompanhe pelos webhooks seller.* (seller.analyzing, seller.approved, seller.refused…) ou por consulta: status, kycSubmittedAt e approvedAt.
5. Com a sub-conta active, cobre com onBehalfOf: "bus_…".
6. Para consultar, capturar ou estornar essa venda, ler o saldo ou pedir um saque da sub-conta, opere como ela com o cabeçalho X-Selectwin-Account.

#Operar como a sub-conta

A venda feita com onBehalfOf pertence à sub-conta. Tudo o que é dela — vendas, saldo, recebíveis, carteiras, saques, clientes — a plataforma alcança enviando X-Selectwin-Account: bus_… junto da sua chave de API: a requisição roda na sub-conta e a resposta vem com merchant.isSubAccount: true. Só chave de API, só sub-conta sua; o cabeçalho nunca é ignorado. Guia: Operar como a sub-conta.

#Estrutura do Objeto Sub-conta

{
  "id": "bus_01hqzvsub1",
  "name": "Loja da Maria",
  "status": "pending",
  "platformFee": { "type": "percentage", "value": 10 },
  "planId": null,
  "createdAt": "2026-10-17T12:00:00.000Z",
  "kycSubmittedAt": null,
  "approvedAt": null,
  "volume30dCents": 0
}

#Estado da plataforma

GET /v1/marketplace

{
  "enabled": true,
  "subAccountCount": 12,
  "subAccountLimit": 20,
  "isSubAccount": false,
  "approvalStatus": "approved"
}

#Precauções

• Chave de API: o recurso é alcançado por chaves de acesso Total. A opção de restringir uma chave só a este recurso ainda não está disponível no painel.
• Sandbox: as sub-contas são um recurso de conta, com uma cópia só (a de produção). Uma escrita com chave sk_test_ responde 409 accountLevelReadOnlyInSandbox; crie e altere sub-contas com sk_live_. As leituras funcionam nos dois ambientes.
• Idempotência: a criação de sub-conta aceita X-Idempotency-Key — use-a em toda retentativa para não cadastrar o mesmo vendedor duas vezes.
• Dados do vendedor: o cadastro (documentos, conta de saque) é preenchido pelo próprio vendedor pelo link, ou por você no painel. Não há como enviar documentos de terceiros por esta API.
• Limite: ao atingir subAccountLimit, a criação responde 422 subAccountLimitReached.

#Webhooks

A plataforma recebe nos seus endpoints de webhook todos os eventos de cada sub-conta a que estiver inscrita — os seller.* do credenciamento (seller.created, seller.analyzing, seller.approved, seller.refused, seller.kycRequired, seller.blocked, seller.disabled, seller.reinstated) e também os das vendas, recebíveis e saques dela (transaction.*, receivable.*, withdrawal.*…). Cada um desses eventos traz, no envelope, o campo account com o id da sub-conta a que pertence; os eventos da sua própria conta não têm o campo. Veja o Catálogo de eventos e a estrutura do evento.

#Recursos Disponíveis

Códigos de erro deste recurso: Catálogo de Códigos de Erro.