Subcontas (Split)

Crie e gerencie subcontas (recebedores de split) programaticamente, incluindo o envio dos documentos KYC.

Função sob liberaçãoEstes endpoints exigem habilitação prévia da sua conta pela nossa equipe. Sem a liberação, a API retorna 403 — Criação de subcontas via API não está habilitada para sua conta. Solicite ao suporte. O cadastro pelo painel continua disponível para todos.

Criar Subconta

POST/v1/sub-accounts

Cria uma subconta com status PENDING (aguardando aprovação da equipe)

Body (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo (PF) ou razão social (PJ) do titular`Ex: "Maria Recebedora"`
`document`	string	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos) do titular`Ex: "12345678901"`
`email`	string	Sim	E-mail do titular`Ex: "maria@email.com"`
`phone`	string	Não	Telefone do titular`Ex: "11999998888"`
`pixKey`	string	Sim	Chave PIX que receberá os repasses`Ex: "maria@email.com"`
`pixKeyType`	string	Sim	Tipo da chave: CPF, CNPJ, EMAIL, PHONE, EVP ou RANDOM`Ex: "EMAIL"`
`autoTransferEnabled`	boolean	Não	Repasse automático diário do saldo (default true). false = o saldo só sai via requisição de saque (POST /v1/sub-accounts/:id/transfer)`Ex: true`
`transferFeePayer`	string	Não	Quem paga a taxa do repasse: SUBACCOUNT (descontada do valor, subconta recebe líquido — default) ou OWNER (subconta recebe cheio, taxa debitada do saldo da conta principal)`Ex: "SUBACCOUNT"`

Enviar Documentos KYC

POST/v1/sub-accounts/:id/documents

Upload multipart de documento do titular (mesmos documentos do cadastro da plataforma)

Body (multipart/form-data)

Parâmetro	Tipo	Obrigatório	Descrição
`file`	file	Sim	Arquivo do documento (JPG, PNG, WEBP, HEIC ou PDF — máx. 5MB)`Ex: —`
`type`	string	Sim	Tipo do documento: RG_FRONT, RG_BACK, SELFIE (PF e PJ) e CONTRACT_SOCIAL (obrigatório para PJ)`Ex: "RG_FRONT"`

Documentos obrigatórios

Pessoa Física (CPF): RG_FRONT, RG_BACK e SELFIE
Pessoa Jurídica (CNPJ): os três acima + CONTRACT_SOCIAL

A resposta de cada upload (e o detalhe da subconta) traz o campo missingDocuments com o que ainda falta. A subconta só pode ser aprovada quando missingDocuments estiver vazio.

Sacar Saldo da Subconta

POST/v1/sub-accounts/:id/transfer

Transfere saldo da subconta para a chave PIX cadastrada dela (saque sob demanda)

Body (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	number	Não	Valor do saque em reais (parcial). Omitido = saldo total da subconta. Respeita o mínimo de saque da plataforma (o mesmo dos saques da conta principal)`Ex: 150.50`
`externalReference`	string	Não	Referência sua para conciliação (máx. 120 caracteres). Devolvida em GET /v1/sub-accounts/:id/transfers e nos webhooks subaccount.transfer.*`Ex: "repasse-loja-01"`

Segurança: IP whitelistado OU Saque via SecretMesma regra do saque da conta principal: o IP de origem precisa estar na whitelist configurada na sua conta, ou, se você não tem IP fixo, solicite ao suporte a habilitação do Saque via Secret e envie o header x-withdrawal-secret em cada requisição de saque.

Quem paga a taxa

transferFeePayer: "SUBACCOUNT" (default): a taxa é descontada do valor sacado — a subconta recebe o líquido (netAmount = amount - fee)
transferFeePayer: "OWNER": a subconta recebe o valor cheio (netAmount = amount) e a taxa é debitada do saldo da sua conta principal — gerando um lançamento CASHOUT próprio no seu histórico ("Taxa de repasse — subconta", externalId SUBFEE-...). Se a conta principal não tiver saldo para a taxa, o saque é bloqueado com 400

A configuração é fixa por subconta (defina em POST ou PATCH /v1/sub-accounts/:id). Em caso de falha no PIX, o valor volta para a subconta — e a taxa, quando paga pela conta principal, volta para ela. Acompanhe a liquidação pelos webhooks subaccount.transfer.completed e subaccount.transfer.failed, ou consultando GET /v1/sub-accounts/:id/transfers.

Webhook do repasse

Cada repasse (sob demanda ou automático) notifica os endpoints inscritos nos eventos subaccount.transfer.* — assinados com o mesmo HMAC dos demais eventos (veja Webhooks):

Payload: subaccount.transfer.completed
{
  "event": "subaccount.transfer.completed",
  "timestamp": "2026-07-18T11:05:00.000Z",
  "data": {
    "transferId": "f0e1d2c3-b4a5-6789-0abc-def123456789",
    "subAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "subAccountName": "Maria Recebedora",
    "externalReference": "repasse-loja-01",
    "amount": 150.5,
    "netAmount": 148.5,
    "fee": 2,
    "feeChargedTo": "SUBACCOUNT",
    "status": "completed",
    "failedReason": null,
    "pixKey": "maria@email.com",
    "pixKeyType": "EMAIL",
    "endToEnd": "E12345678202607181105abcdef12345",
    "createdAt": "2026-07-18T11:00:00.000Z",
    "processedAt": "2026-07-18T11:05:00.000Z"
  }
}

Atualizar Subconta

PATCH/v1/sub-accounts/:id

Atualiza a config de repasse (autoTransferEnabled, transferFeePayer), chave PIX e ativação. Dados do titular só enquanto PENDING

Body (JSON) — todos opcionais

Parâmetro	Tipo	Obrigatório	Descrição
`autoTransferEnabled`	boolean	Não	true = repasse automático diário; false = o saldo só sai via POST /v1/sub-accounts/:id/transfer`Ex: false`
`transferFeePayer`	string	Não	SUBACCOUNT (taxa descontada do valor — subconta recebe líquido) ou OWNER (subconta recebe cheio — taxa debitada da conta principal)`Ex: "OWNER"`
`pixKey`	string	Não	Nova chave PIX de recebimento dos repasses`Ex: "maria@email.com"`
`pixKeyType`	string	Não	CPF, CNPJ, EMAIL, PHONE, EVP ou RANDOM`Ex: "EMAIL"`
`phone`	string	Não	Telefone do titular`Ex: "11999998888"`
`active`	boolean	Não	false desativa a subconta (não recebe split nem repasses). Não há DELETE — desativação é feita por aqui`Ex: false`
`name / document / email`	string	Não	Dados do titular — só podem ser alterados enquanto a subconta está PENDING`Ex: —`

Use este endpoint para desligar o repasse automático depois da criação ({"autoTransferEnabled": false}) ou para trocar quem paga a taxa. A resposta devolve a subconta completa com os valores atualizados. No painel, a mesma configuração fica na página da subconta (Subcontas → extrato → Configurações de repasse, ou na visão da subconta pelo seletor da sidebar).

Consultas

GET/v1/sub-accounts

Lista as subcontas da conta com saldo, status e config de repasse (autoTransferEnabled, transferFeePayer)

GET/v1/sub-accounts/:id

Detalhe da subconta com documentos enviados e missingDocuments

GET/v1/sub-accounts/:id/transfers

Histórico paginado dos repasses — valor, taxa, feeChargedTo, status, endToEnd e externalReference (conciliação)

GET/v1/sub-accounts/:id/documents

Lista os documentos KYC enviados (com status individual)

Fluxo completo

Criar a subconta (POST /v1/sub-accounts) → status PENDING
Enviar os documentos até missingDocuments ficar vazio
Aguardar a aprovação manual da nossa equipe — você recebe o webhook subaccount.approved (ou subaccount.rejected com o motivo), e também pode consultar o status por GET /v1/sub-accounts
Usar no split: com status APPROVED, use o subAccountId no campo split ao criar cobranças PIX

Com autoTransferEnabled: true (default), o saldo acumulado é repassado automaticamente 1x por dia para a chave PIX cadastrada. Com false, o saldo só sai quando você solicitar via POST /v1/sub-accounts/:id/transfer. Veja o guia completo em Split de Pagamentos e os eventos em Webhooks.

Códigos de Erro

Código	Descrição
`403`	Criação de subcontas via API não habilitada para a conta — solicite a liberação ao suporte
`400`	Dados inválidos (CPF/CNPJ, chave PIX) ou CPF/CNPJ já cadastrado em outra subconta sua
`400`	Arquivo inválido no upload (formato/tamanho não permitido)
`400`	Saque: saldo insuficiente, valor abaixo do mínimo ou conta principal sem saldo para a taxa (modo OWNER)
`404`	Subconta não encontrada (ou pertence a outra conta)

Requisição (criar + documentos)

curl -X POST "https://api.activepayments.com.br/api/v1/sub-accounts" \
  -H "Authorization: ApiKey PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Recebedora",
    "document": "12345678901",
    "email": "maria@email.com",
    "phone": "11999998888",
    "pixKey": "maria@email.com",
    "pixKeyType": "EMAIL",
    "autoTransferEnabled": false,
    "transferFeePayer": "OWNER"
  }'

HTTP 201 Created
{
  "success": true,
  "data": {
    "subAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Maria Recebedora",
    "document": "12345678901",
    "email": "maria@email.com",
    "phone": "11999998888",
    "pixKey": "maria@email.com",
    "pixKeyType": "EMAIL",
    "balance": 0,
    "status": "PENDING",
    "active": true,
    "autoTransferEnabled": true,
    "transferFeePayer": "SUBACCOUNT",
    "rejectionReason": null,
    "createdAt": "2026-07-09T12:00:00.000Z",
    "missingDocuments": ["RG_FRONT", "RG_BACK", "SELFIE"],
    "message": "Subconta criada. Envie os documentos KYC em POST /v1/sub-accounts/:id/documents — a aprovação é feita pela nossa equipe."
  }
}

Saque, config e consulta de repasses

# Saque parcial com referência de conciliação
curl -X POST "https://api.activepayments.com.br/api/v1/sub-accounts/{subAccountId}/transfer" \
  -H "Authorization: ApiKey PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 150.50, "externalReference": "repasse-loja-01"}'

# Saque do saldo total (body vazio)
curl -X POST "https://api.activepayments.com.br/api/v1/sub-accounts/{subAccountId}/transfer" \
  -H "Authorization: ApiKey PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Alterar config de repasse depois de criada
curl -X PATCH "https://api.activepayments.com.br/api/v1/sub-accounts/{subAccountId}" \
  -H "Authorization: ApiKey PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"autoTransferEnabled": false, "transferFeePayer": "OWNER"}'

# Consultar os repasses (status, taxa, endToEnd)
curl -X GET "https://api.activepayments.com.br/api/v1/sub-accounts/{subAccountId}/transfers?page=1&limit=20" \
  -H "Authorization: ApiKey PUBLIC_KEY:SECRET_KEY"

Saque: HTTP 201 Created
{
  "success": true,
  "data": {
    "transferId": "f0e1d2c3-b4a5-6789-0abc-def123456789",
    "subAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalReference": "repasse-loja-01",
    "amount": 150.5,
    "netAmount": 148.5,
    "fee": 2,
    "status": "PROCESSING"
  }
}

GET /transfers: HTTP 200 OK
{
  "success": true,
  "data": [
    {
      "transferId": "f0e1d2c3-b4a5-6789-0abc-def123456789",
      "subAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "externalReference": "repasse-loja-01",
      "amount": 150.5,
      "netAmount": 148.5,
      "fee": 2,
      "feeChargedTo": "SUBACCOUNT",
      "status": "COMPLETED",
      "failedReason": null,
      "pixKey": "maria@email.com",
      "pixKeyType": "EMAIL",
      "endToEnd": "E12345678202607181105abcdef12345",
      "createdAt": "2026-07-18T11:00:00.000Z",
      "processedAt": "2026-07-18T11:05:00.000Z",
      "completedAt": "2026-07-18T11:05:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}