Sub-contas - Criar
Visão Geral
Este endpoint cadastra uma nova sub-conta sob a sua plataforma: o vendedor que passará a vender por meio de você. A sub-conta nasce com o status pending e precisa completar o credenciamento (pelo link ou pelo painel) antes de cobrar e sacar.
Precauções
- A sua conta precisa ter a função de marketplace ligada e aprovada (
GET /v1/marketplace→enabled: true,approvalStatus: "approved"). Caso contrário a API responde403. - Use
X-Idempotency-Key: a criação é idempotente. Uma retentativa com a mesma chave devolve a mesma sub-conta em vez de cadastrar o vendedor duas vezes. - Só uma forma de taxa por sub-conta:
platformFeeouplanId. Enviar os dois é recusado com400. - O
planIdprecisa ser um plano de taxas da sua plataforma; um plano inexistente responde404antes de criar a sub-conta. - Recurso de conta: use uma chave
sk_live_(comsk_test_a resposta é409 accountLevelReadOnlyInSandbox). - O limite de sub-contas da conta (
subAccountLimit) vale aqui: no teto,422 subAccountLimitReached.
Requisição
HTTP
POST /v1/marketplace/sub-accountsCorpo da Requisição
JSON
{
"companyName": "Loja da Maria",
"platformFee": { "type": "percentage", "value": 10 }
}Ou, com um plano de taxas:
JSON
{
"companyName": "Loja da Maria",
"planId": "rate_01hqzvplan1"
}Atributos do Corpo
| Atributo | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|
companyName | string | Sim | Nome do vendedor (1–100 caracteres). O vendedor completa a razão social e os documentos no credenciamento | "Loja da Maria" |
platformFee | object | Não | A taxa simples da plataforma sobre cada venda da sub-conta | — |
platformFee.type | string | Sim* | percentage (percentual da venda) ou flat (valor fixo por venda) | "percentage" |
platformFee.value | number | Sim* | Com percentage, um número maior que 0 até 100; com flat, o valor em centavos (maior que 0) | 10 |
planId | string | Não | Um plano de taxas da plataforma (rate_…). Exclui platformFee | "rate_01hqzvplan1" |
* obrigatório quando platformFee é enviado.
Resposta
Sucesso (201 Created)
JSON
{
"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": null
}Os campos estão descritos em Visão Geral. Guarde o id: é o valor de onBehalfOf nas cobranças e o {companyId} das demais operações.
O webhook seller.created é enviado aos seus endpoints assim que a sub-conta existe.
Erros
| HTTP | error.code | Quando |
|---|---|---|
| 400 | invalidParameters | Corpo inválido (nome vazio, taxa fora da faixa, platformFee e planId juntos) |
| 403 | marketplaceNotEnabled | A função de marketplace não está ligada para a sua conta |
| 403 | marketplaceNotApproved | A função está ligada, mas ainda aguarda (ou não recebeu) a aprovação de compliance |
| 403 | companyNotActive | A sua própria conta não está ativa |
| 404 | planNotFound | O planId não é um plano da sua plataforma |
| 409 | accountLevelReadOnlyInSandbox | Escrita com chave de sandbox |
| 422 | marketplaceNested | A conta autenticada é uma sub-conta — sub-conta não cria sub-conta |
| 422 | subAccountLimitReached | A conta atingiu o limite de sub-contas. Fale com o seu gerente de conta para ampliá-lo |
| 422 | marketplaceUserRequired | A conta da plataforma não tem um titular registrado. Fale com o suporte |
Exemplo
Shell
curl -X POST "https://api.selectwin.io/v1/marketplace/sub-accounts" \
-H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: 7a1f2c0e-4b7d-4d0a-9c3e-1f2a3b4c5d6e" \
-d '{ "companyName": "Loja da Maria", "platformFee": { "type": "percentage", "value": 10 } }'Próximo passo
Gere o link de credenciamento e envie ao vendedor. A sub-conta só cobra e saca depois de active.
Atualizado em 21 de outubro de 2026