Subcontas e split

Subcontas recebem parte das vendas (split). Leia antes Subcontas e split para saber o que cada conta faz.

Rotas

Rota
POST /subaccounts criar (admin)
GET /subaccounts lista (?status=, ?provider_account_id=, ?q=)
GET /subaccounts/:id uma subconta, com totals e as últimas vendas divididas em splits
PATCH /subaccounts/:id mudar name e metadata na SuyPay
POST /subaccounts/:id/sync consultar a situação na conta agora
POST /subaccounts/:id/onboarding-link link de cadastro para o titular (Pagar.me, Asaas)
GET /subaccounts/:id/balance saldo da subconta
POST /subaccounts/:id/withdrawals sacar para o destino da subconta (exige Idempotency-Key)
GET /subaccounts/:id/withdrawals saques dessa subconta

Chaves só cobranças não chegam a essas rotas.

Criar

curl https://api.suypay.com/v1/subaccounts \
  -H "Authorization: Bearer suy_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider_account_id": "pa_...",
    "type": "individual",
    "name": "João Souza",
    "document": "12345678909",
    "email": "joao@email.com",
    "phone": "11912345678",
    "birthdate": "1990-05-20",
    "mother_name": "Ana Souza",
    "occupation": "Vendedor",
    "monthly_income": 500000,
    "address": { "zip": "01310-100", "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP" },
    "bank_account": { "bank": "341", "branch": "1234", "account": "123456", "account_digit": "7", "type": "checking" },
    "transfer_interval": "weekly"
  }'
Campo
provider_account_id a conta conectada onde a subconta fica
type individual (CPF) ou company (CNPJ). Sem ele, vem do tamanho do documento
name, document sempre
email, phone, birthdate (AAAA-MM-DD), mother_name, occupation, monthly_income (centavos) quando a conta pede
address zip, street, number, neighborhood, city, state, complement
bank_account bank (3 números), branch, branch_digit, account, account_digit, type (checking/savings), holder_name. Mesmo CPF/CNPJ da subconta
pix_key { "key_type": "cpf" | "cnpj" | "email" | "phone" | "random", "key" } (Woovi)
company trading_name (razão social), company_type (Asaas: MEI, LIMITED, INDIVIDUAL, ASSOCIATION; Pagar.me: LTDA, MEI…), founding_date, annual_revenue (centavos)
partner sócio administrador de empresa (Pagar.me): mesmos campos de pessoa
transfer_interval repasse automático na Pagar.me: daily, weekly ou monthly
metadata até 20 chaves suas

Se faltar um campo que a conta exige, a resposta é 400 dizendo qual, em error.param. GET /providers mostra em capabilities.subaccounts.requires o que cada conta pede.

{
  "id": "sub_...",
  "object": "subaccount",
  "status": "pending",
  "status_detail": "Falta o titular concluir o cadastro (prova de vida). Já pode vender, mas não sacar.",
  "provider": "pagarme",
  "provider_account_id": "pa_...",
  "provider_subaccount_id": "re_...",
  "type": "individual",
  "name": "João Souza",
  "document": "12345678909",
  "details": { "bank_account": { "bank": "341", "branch": "1234", "account": "****456-7", "holder": "João Souza" } }
}

No Asaas, a chave de API da subconta (que o Asaas mostra uma vez só) fica guardada com criptografia na SuyPay, para consultar a situação e o saldo dela. Ela nunca volta pela API.

Link de cadastro

curl -X POST https://api.suypay.com/v1/subaccounts/sub_.../onboarding-link -H "Authorization: Bearer suy_live_..."

{ "url": "https://...", "expires_at": "2026-10-19T17:00:00Z", "qr_code_base64": null }

Dividir uma cobrança

Mande splits em POST /payments:

Campo
subaccount_id sub_... ativa ou em cadastro
amount centavos do valor da venda, ou
percentage porcentagem do valor da venda (até duas casas)

Todas as subcontas precisam ser da mesma conta conectada, e as partes somam menos que o valor, deixando o bastante para a taxa. A cobrança devolvida traz splits: [{ "subaccount_id", "amount" }] em centavos.

Sacar

curl https://api.suypay.com/v1/subaccounts/sub_.../withdrawals \
  -H "Authorization: Bearer suy_live_..." \
  -H "Idempotency-Key: repasse-joao-2026-10" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 150000 }'

A resposta é um objeto payout com subaccount_id e destination: { "type": "subaccount" }. Na Woovi, amount é ignorado: o saque leva o saldo inteiro. A subconta precisa estar active.

Avisos

subaccount.created e subaccount.updated chegam no seu webhook com o objeto subaccount. Os saques avisam como qualquer saque (payout.*).