Subcontas merchant

Subcontas merchant são carteiras lógicas vinculadas à sua conta GoatPay principal. Servem para separar saldo por produto, parceiro ou unidade de negócio, sem abrir outra conta na GoatPay.

Habilitação

Etapa	Onde	Detalhe
Solicitar	Dashboard → Contas → Subcontas	Informe WhatsApp; status em `access-status`
Aprovação	Equipe GoatPay (admin)	Ativa `merchantSubaccountsEnabled` na conta
PIX em subconta	Admin, após habilitar subcontas	Flag `merchantSubaccountsPixEnabled`

Sem habilitação, a API retorna 403 em rotas subaccount/* e ao enviar subaccountId no PIX. A solicitação de acesso não existe na API pública hoje — apenas no dashboard.

Permissões na API key

Marque o grupo Subcontas ao criar a chave. Cada rota exige uma permissão:

Permissão	Uso
`subaccount/create`	Criar subconta
`subaccount/get`	Consultar por `id` ou `externalReference`
`subaccount/list`	Listar subcontas
`subaccount/update`	Renomear ou `ACTIVE` / `DISABLED`
`subaccount/delete`	Excluir (saldo zerado; retorna `{ id }`)
`subaccount/balance`	Saldo da subconta
`subaccount/add-balance`	Conta principal → subconta
`subaccount/remove-balance`	Subconta → conta principal
`subaccount/transfer`	Entre duas subcontas
`subaccount/lock` / `subaccount/unlock`	Bloqueio operacional
`subaccount/set-limits`	Limites diário/mensal/por transação
`subaccount/set-pricing`	Acréscimo de taxa PIX entrada/saída (somado à taxa principal)
`subaccount/get`	`GET /subaccount/pricing` — preview das taxas com `lines[].label`

Para PIX na subconta, use também payment-pix/create e/ou transfer-pix/create na mesma chave.

Conceitos

Conceito	Descrição
Conta principal	Dono do saldo “global”; movimentações `add-balance` / `remove-balance` cruzam main ↔ sub
`externalReference`	ID do seu sistema (máx. 64). Obrigatório na API pública no `create`
Trilho	Somente Padrão — movimentações e PIX em subconta usam saldo `*White`; não há parâmetro `pixRail` na API
Saldo	Use `spendableWhite` (e campos `availableWhite` / `lockedWhite` / `pendingWhite`)
Limites	Validados por soma de débitos `COMPLETED` no período (sem contador em tabela)
`lockMode`	`full`, `withdraw_only`, `deposit_only` — afeta PIX e movimentações

Fluxo recomendado

1. Habilitar e criar subconta

Após aprovação no dashboard, crie a subconta com cadastro KYC (PF ou PJ): POST /subaccount/create com nome, CPF, data de nascimento, CEP e, para PJ, CNPJ, razão social, site e comprovante em multipart.No app GoatPay, configure taxas globais em Subcontas e use Gerenciar subconta para saldo, transferências, limites, bloqueios e taxas PIX in/out.Criar subconta

2. Alocar saldo (opcional)

POST /subaccount/add-balance transfere da conta principal para a subconta.Ou receba PIX direto na subconta (passo 4).

3. Configurar limites e bloqueios (opcional)

set-limits, lock / unlock conforme política de risco.

4. PIX na subconta

Não há rotas /subaccount/payment-pix. Use as rotas PIX normais com subaccountId no body (veja abaixo).

5. Reconciliar

GET /subaccount/balance ou get / list. Extrato filtrado por subconta (API key ou dashboard): GET /v1/account/transactions?subaccountId={id} ou merchantSubaccountId={id}. Cobranças PIX da subconta: GET /v1/payment-pix/list?subaccountId={id}.Extrato da conta · Listar cobranças PIX

Receber PIX (cobrança QR) na subconta

Não existe POST /subaccount/payment-pix/create. Use a rota padrão de cobrança com o ID da subconta:

curl -X POST 'https://api.goatpay.com.br/v1/payment-pix/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 100,
    "description": "Pedido loja A",
    "subaccountId": "clx_subconta",
    "externalReference": "pedido-9001"
  }'

Requisito	Detalhe
Permissão	`payment-pix/create`
Flag da conta	`merchantSubaccountsPixEnabled`
Subconta	`ACTIVE` obrigatório; `DISABLED` ou excluída (soft delete) não operam PIX. Não bloqueada para depósito (`lockMode` ≠ `full` / `deposit_only`)
Trilho	Não envie `subaccountId` em PIX Livre — retorna 400
Liquidação	O líquido credita o saldo da subconta no trilho da chave
Lucro (pricing)	Diferença entre taxa cobrada e taxa da subconta pode ir para a conta principal (`SUBACCOUNT_PROFIT`)

Consulta e listagem: Consultar cobrança (por id ou externalReference); Listar com ?subaccountId= para filtrar só aquela subconta. A resposta inclui subaccountId quando a cobrança foi criada com subconta. Webhooks payment.created / payment.paid não mudam. Documentação completa de criar cobrança PIX

Enviar PIX (saque) da subconta

Mesmo padrão: rota de saque existente + subaccountId:

curl -X POST 'https://api.goatpay.com.br/v1/transfer-pix/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 50,
    "description": "Repasse fornecedor",
    "pixKey": "12345678909",
    "pixKeyType": "CPF",
    "subaccountId": "clx_subconta",
    "coverFee": true
  }'

Requisito	Detalhe
Permissão	`transfer-pix/create` (ou alias `payouts/create`)
Flag da conta	`merchantSubaccountsPixEnabled`
Saldo	Débito no saldo spendable da subconta no trilho da operação
Bloqueio	`withdraw_only` ou `full` impedem saque
Limites	`dailyLimit`, `monthlyLimit`, `perTransactionLimit` da subconta

Documentação de enviar PIX

Movimentação interna (sem PIX)

Operação	Rota	Efeito
Principal → sub	`POST /subaccount/add-balance`	Débito na main, crédito na sub
Sub → principal	`POST /subaccount/remove-balance`	Débito na sub, crédito na main
Sub → sub	`POST /subaccount/transfer`	Entre duas subcontas da mesma conta

Rotas add-balance, remove-balance e transfer são idempotentes quando você repete o mesmo externalReference (ou payload equivalente derivado internamente).

Saldo da subconta

GET /subaccount/balance?id=... ou ?externalReference=... Exemplo de balance em GET /subaccount/get/:id:

{
  "availableWhite": 500,
  "pendingWhite": 0,
  "lockedWhite": 0,
  "spendableWhite": 500
}

Na API pública, balance expõe apenas campos *White. Use spendableWhite como saldo utilizável para saques e remove-balance. Exclusão (delete) exige saldo White zerado.

Extrato filtrado

GET /v1/account/transactions?subaccountId={id} inclui, entre outros:

Tipo	Origem
`SUBACCOUNT_ADD_BALANCE`	`add-balance`
`SUBACCOUNT_REMOVE_BALANCE`	`remove-balance`
`SUBACCOUNT_TRANSFER`	`transfer` entre subs
PIX com `subaccountId`	Cobrança/saque/reembolso na subconta

Consultar taxas antes de set-pricing para ver totalPercentFee / totalFixedFee por operação.

Limites e bloqueio

Limites (set-limits): valores em reais ou null para remover. Gasto validado por agregação de transações de débito COMPLETED vinculadas à subconta (fuso America/Sao_Paulo). Bloqueio (lock):

`mode`	Depósito PIX / add-balance	Saque PIX / remove-balance
`full`	Bloqueado	Bloqueado
`deposit_only`	Bloqueado	Permitido
`withdraw_only`	Permitido	Bloqueado

MED e reembolso

MED: quando o depósito PIX estava vinculado à subconta (subaccountId na cobrança), o bloqueio reduz o disponível da subconta e aumenta lockedWhite — não usa blockedAmount da conta principal. MED em PIX da conta principal segue o fluxo normal na main. Veja também o guia de MEDs.
Reembolso PIX: a taxa de saída segue o pricing da subconta; o débito reserva saldo na subconta (líquido retido + taxa). Informe subaccountId em POST /refunds/create quando o depósito pertence à subconta. Na conclusão do estorno, lucro de subconta creditado na main pode ser revertido. Solicitar reembolso

Taxas (PIX entrada e PIX saída)

Subcontas pagam: taxa da conta principal + acréscimo configurado.

Operação	`operation` na API
PIX entrada (cobrança)	`PIX_WHITE_DEPOSIT`
PIX saída (transferência)	`PIX_WHITE_TRANSFER`

API pública: POST /subaccount/set-pricing define acréscimo por subconta. O valor soma à taxa da conta principal; na liquidação do PIX in, o acréscimo credita a conta principal (SUBACCOUNT_PROFIT).
Preview: GET /subaccount/pricing com id ou externalReference retorna simulação antes de cobrar. Definir taxas

Endpoints

Criar

Nova subconta com externalReference.

Consultar

Por id na URL.

Por referência

GET .../get-by-ref/{externalReference}.

Listar

Paginação e filtro status.

Saldo

Query id ou externalReference.

Adicionar saldo

Main → subconta.

Remover saldo

Subconta → main.

Transferir entre subs

fromSubaccountId → toSubaccountId.

Atualizar

Nome e status ACTIVE / DISABLED.

Excluir

Saldo zerado no Padrão.

Bloquear

full, withdraw_only, deposit_only.

Desbloquear

Volta ao modo normal.

Limites

Diário, mensal e por transação.

Taxas

Acréscimo PIX in/out.

Para excluir uma subconta, zere o saldo (remove-balance ou saques) e use POST /subaccount/delete. A resposta confirma com { "id": "..." }. Subcontas com saldo retornam erro 400.

​Habilitação

​Permissões na API key

​Conceitos

​Fluxo recomendado

​Receber PIX (cobrança QR) na subconta

​Enviar PIX (saque) da subconta

​Movimentação interna (sem PIX)

​Saldo da subconta

​Extrato filtrado

​Limites e bloqueio

​MED e reembolso

​Taxas (PIX entrada e PIX saída)

​Endpoints

Criar

Consultar

Por referência

Listar

Saldo

Adicionar saldo

Remover saldo

Transferir entre subs

Atualizar

Excluir

Bloquear

Desbloquear

Limites

Taxas

Habilitação

Permissões na API key

Conceitos

Fluxo recomendado

Receber PIX (cobrança QR) na subconta

Enviar PIX (saque) da subconta

Movimentação interna (sem PIX)

Saldo da subconta

Extrato filtrado

Limites e bloqueio

MED e reembolso

Taxas (PIX entrada e PIX saída)

Endpoints