Splits de recebíveis

Os splits dividem automaticamente a receita de cada cobrança recorrente da assinatura entre você (o merchant) e outros destinatários — sócios, parceiros, afiliados ou subcontas. Você define quem recebe, quanto (percentual ou valor fixo em centavos) e quem arca com a taxa de processamento e com eventuais chargebacks. Use os endpoints abaixo para adicionar, listar, consultar, atualizar e remover esses repasses.

Split (repasse): regra que encaminha parte do valor de uma cobrança para outra conta no momento da liquidação. Em vez de receber 100% e repassar manualmente, a Selectwin faz a divisão para você a cada ciclo da assinatura.

Como funciona

Toda assinatura nasce com 100% da receita indo para o merchant (a conta dona da assinatura). Cada split que você adiciona "fatia" uma parte desse total para outro recipient. O servidor mantém o controle de quanto já foi alocado:

• totalPercentage — soma dos percentuais já configurados em splits.
• remainingPercentage — quanto da receita ainda não foi alocado (em pontos percentuais).
• remainingAmount — o mesmo restante, mas estimado em centavos (string), com base no valor atual da assinatura.

A divisão é aplicada a cada cobrança recorrente: ao adicionar um split, ele passa a valer dos próximos ciclos em diante, não retroage a cobranças já liquidadas. Cada split carrega duas regras de responsabilidade:

• chargeProcessingFee — se true, a taxa de processamento da Selectwin é descontada da fatia desse destinatário (em vez de sair só da sua).
• liable — se true, esse destinatário é corresponsável por chargebacks (estornos forçados pelo portador); o valor estornado pode ser debitado dele.

O objeto split

Quando usar

• Marketplaces e plataformas que cobram uma assinatura do cliente final e precisam repassar parte ao vendedor/criador a cada ciclo.
• Comissões de afiliados recorrentes (um percentual fixo da mensalidade vai para quem indicou).
• Sociedades que dividem a receita de um produto recorrente entre contas distintas.

Quando não usar: para uma divisão pontual de uma única cobrança avulsa, use os splits da própria transação (recurso Transactions), não os da assinatura. Splits de assinatura são para repasses que se repetem a cada ciclo.

Requisição

Headers

Toda chamada exige autenticação por header SelectKey; chamadas com corpo (POST, PUT) exigem Content-Type: application/json.

Veja Autenticação e Convenções (camelCase, centavos, datas ISO 8601 UTC, IDs opacos).

Adicionar um split

POST /v1/subscriptions/{subscriptionId}/splits

Cria um novo repasse na assinatura. A resposta é o resumo atualizado de todos os splits — não a assinatura inteira nem só o split criado.

Parâmetros de caminho

Corpo

curl -X POST "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "acc_abc123",
    "type": "percentage",
    "value": 10
  }'

Resposta — 200 OK

{
  "subscription": "subs_01hqzvabc",
  "splits": [
    {
      "id": "split_01hqzvabc",
      "recipient": "bus_9876543210",
      "type": "percentage",
      "value": 30,
      "chargeProcessingFee": true,
      "liable": true,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "totalPercentage": 30,
  "remainingPercentage": 60,
  "remainingAmount": "9900",
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": {
    "self": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits", "method": "POST", "description": "Add splits to subscription." },
    "list": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits", "method": "GET", "description": "List splits of a subscription." }
  }
}

O remainingAmount vem como string ("9900"), não como número. Converta para inteiro antes de fazer contas.

Listar os splits

GET /v1/subscriptions/{subscriptionId}/splits

Retorna a lista paginada de splits da assinatura.

Parâmetros

curl "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits?limit=20&sort=descending" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta — 200 OK

{
  "offset": 0,
  "limit": 20,
  "total": 2,
  "hasMore": false,
  "page": { "current": 1, "total": 1, "offset": { "first": 0, "prev": null, "next": null, "last": 0 } },
  "data": [
    {
      "id": "split_01hqzvabc",
      "recipient": "bus_other",
      "type": "percentage",
      "value": 30,
      "chargeProcessingFee": true,
      "liable": true,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": { "self": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits", "method": "GET" } }
}

Os splits ficam em data; o envelope traz a paginação (offset, limit, total, hasMore, page). Para detalhes do esquema de páginas, veja Paginação.

Consultar um split

GET /v1/subscriptions/{subscriptionId}/splits/{splitId}

Retorna um único split pelo seu ID. Aqui o splitId vai no caminho.

Parâmetros de caminho

curl "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits/split_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta — 200 OK

{
  "id": "split_01hqzvabc",
  "recipient": "bus_other",
  "type": "percentage",
  "value": 30,
  "chargeProcessingFee": true,
  "liable": true,
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": { "self": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits/split_01hqzvabc", "method": "GET" } }
}

Diferente do resumo retornado por POST/DELETE, aqui o objeto raiz é o próprio split (com merchant e _links ao lado), sem totalPercentage/remainingPercentage.

Atualizar um split

PUT /v1/subscriptions/{subscriptionId}/splits/{splitId}

Substitui a configuração de um split existente. Como é um PUT, envie o objeto completo (recipient, type, value) — campos omitidos não são preservados.

Parâmetros de caminho

Corpo

curl -X PUT "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits/split_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "acc_abc123",
    "type": "percentage",
    "value": 10
  }'

Resposta — 200 OK

Retorna o split atualizado (mesmo formato da consulta):

{
  "id": "split_01hqzvabc",
  "recipient": "bus_other",
  "type": "percentage",
  "value": 30,
  "chargeProcessingFee": true,
  "liable": true,
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": { "self": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits/split_01hqzvabc", "method": "GET" } }
}

Remover um split

DELETE /v1/subscriptions/{subscriptionId}/splits?splitId=...

Remove um split da assinatura. O split a remover é identificado pelo splitId na query string (não no caminho). A resposta é o resumo atualizado, com remainingPercentage/remainingAmount recalculados.

Parâmetros

curl -X DELETE "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits?splitId=split_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta — 200 OK

{
  "subscription": "subs_01hqzvabc",
  "splits": [
    {
      "id": "split_01hqzvabc",
      "recipient": "bus_9876543210",
      "type": "percentage",
      "value": 30,
      "chargeProcessingFee": true,
      "liable": true,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "totalPercentage": 30,
  "remainingPercentage": 60,
  "remainingAmount": "9900",
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": {
    "self": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits", "method": "DELETE", "description": "Remove split of subscription." },
    "list": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits", "method": "GET", "description": "List splits of subscription." },
    "create": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits", "method": "POST", "description": "Add split of subscription." }
  }
}

A remoção libera a fatia daquele split de volta para o restante não alocado — note remainingPercentage/remainingAmount mudando no resumo.

Erros

Trate sempre pelo error.code, nunca pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

• Acompanhe o remainingPercentage/remainingAmount retornados no resumo antes de adicionar outro split, para não exceder 100% da receita. Lembre que remainingAmount vem como string — converta para inteiro.
• Trate o value segundo o type: percentual (0–100) para percentage, centavos para flat. Misturar as duas leituras é a fonte mais comum de bug.
• Em atualizações (PUT), envie o objeto completo. Por ser substituição, omitir um campo não o mantém — reenvie recipient, type e value.
• Cuidado com o splitId no DELETE: ele vai na query string (?splitId=...), ao contrário do GET/PUT, que usam o caminho. Validar o splitId contra o padrão ^[a-z]+_[A-Za-z0-9]+$ evita um 400.
• Decida chargeProcessingFee e liable conscientemente: definem quem absorve a taxa e quem responde por chargebacks. Documente o acordo comercial antes de configurar.
• Trate IDs como opacos. Armazene id, recipient e subscriptionId como strings inteiras; não faça parsing nem confie no prefixo.
• Não retroage: splits valem a partir das próximas cobranças do ciclo. Ajuste-os antes da data de cobrança para que entrem em vigor no ciclo desejado.

Veja também

• Visão geral de Subscriptions — o que é uma assinatura e seu ciclo de vida.
• Criar assinatura e Consultar assinatura — obtenha o subscriptionId.
• Ciclos — quando cada cobrança (e portanto cada split) é aplicada.
• Itens — composição da receita que será dividida.
• Convenções da API · Códigos de Erro · Paginação