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 `*Padrao`; não há parâmetro `pixRail` na API
Saldo	Use `spendablePadrao` (e campos `availablePadrao` / `lockedPadrao` / `pendingPadrao`)
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

Portal Wallet

O Portal Wallet permite que o titular ou operador de uma subconta acesse uma carteira dedicada em wallet.goatpay.com.br, separada do login da conta principal em app.goatpay.com.br. Cada subconta pode ter um usuário de portal (e-mail + senha). A sessão é isolada da conta merchant.

O que o operador vê

Recurso	Descrição
Dashboard	Saldo, métricas do dia, gráfico de volume e atividade recente
Depositar / Transferir	PIX na subconta (trilho Padrão)
Extrato e resumo	Movimentações filtradas pela subconta
Disputas (MED)	MEDs vinculados a transações da subconta
Conta	Segurança, 2FA, senha

Use a API pública v1/subaccount/* com header X-API-Key. Todas as rotas abaixo exigem permissões específicas na chave (subaccount/portal/*).

Na criação da subconta

Inclua portalEmail e portalPassword em POST /v1/subaccount/create:

curl -X POST 'https://api.goatpay.com.br/v1/subaccount/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "personType": "PF",
    "fullName": "Maria Silva",
    "cpf": "52998224725",
    "birthDate": "1990-05-15",
    "postalCode": "01310100",
    "externalReference": "loja-parceiro-a",
    "portalEmail": "operador@empresa.com",
    "portalPassword": "SenhaForte!123"
  }'

Campo	Tipo	Obrigatório	Descrição
`portalEmail`	string	Se quiser portal	E-mail de login no Portal Wallet
`portalPassword`	string	Sim, se informar `portalEmail`	Senha inicial (mín. 8 caracteres, maiúscula, minúscula, número e símbolo)

Se ambos forem informados, o acesso fica ativo na hora. O operador entra em wallet.goatpay.com.br/login com e-mail e senha — sem confirmação por e-mail.

Se você informar portalEmail sem portalPassword, a API retorna erro.

POST /v1/subaccount/portal/setup — permissão subaccount/portal/setup:

curl -X POST 'https://api.goatpay.com.br/v1/subaccount/portal/setup' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalReference": "loja-parceiro-a",
    "email": "operador@empresa.com",
    "password": "SenhaForte!123"
  }'

Campo	Obrigatório	Descrição
`id` ou `externalReference`	Sim (um dos dois)	Identifica a subconta
`email`	Sim	E-mail de login (único na plataforma para portal)
`password`	Sim	Senha do operador

Resposta de sucesso: { "success": true, "mode": "portal_ready" }.

Consultar status do portal (API key)

GET /v1/subaccount/portal/status — permissão subaccount/portal/get

Sem query: lista todas as subcontas com estado do portal.
Com ?id= ou ?externalReference=: status de uma subconta.

Exemplo de item na resposta:

{
  "subaccountId": "clx_subconta",
  "subaccountName": "Loja Parceiro",
  "portal": {
    "state": "active",
    "email": "operador@empresa.com",
    "emailVerified": true,
    "twoFactorEnabled": false,
    "lastLoginAt": "2026-06-08T14:22:00.000Z"
  }
}

Estados possíveis:

Estado	Significado
`none`	Sem login de portal configurado
`active`	E-mail e senha cadastrados; operador pode entrar
`disabled`	Portal revogado pelo merchant
`pending_password`	Legado — reconfigure com `portal/setup`
`invite_pending`	Legado — reconfigure com `portal/setup`
`pending_verification`	Legado — contas antigas antes da remoção da verificação por e-mail

Outras rotas de gestão (API key)

Método	Rota	Permissão	Uso
`POST`	`/v1/subaccount/portal/update-email`	`subaccount/portal/update-email`	Alterar e-mail do operador
`POST`	`/v1/subaccount/portal/revoke`	`subaccount/portal/revoke`	Revogar acesso ao portal
`POST`	`/v1/subaccount/portal/reset-2fa`	`subaccount/portal/reset-2fa`	Resetar 2FA do operador

Alternativa: dashboard merchant

As mesmas operações estão disponíveis no app em Contas → Subcontas → Gerenciar subconta → aba Portal. O operador entra em wallet.goatpay.com.br/login com o e-mail e a senha cadastrados pelo merchant. A sessão fica limitada à subconta vinculada — saldo, PIX, extrato e MED respeitam os mesmos limites da API pública.

Relação com a API pública

Criar/movimentar subcontas via API key continua em v1/subaccount/*.
O Portal Wallet é opcional e voltado a operação humana na interface web.
PIX, extrato e MED no wallet respeitam os mesmos saldos e bloqueios da subconta no trilho Padrão.

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. Opcionalmente configure o Portal Wallet na aba Portal ou com portalEmail + portalPassword na criação (senha obrigatória junto com o e-mail).Criar subconta · Portal Wallet

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`)
Liquidação	O líquido credita o saldo da subconta
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:

{
  "availablePadrao": 500,
  "pendingPadrao": 0,
  "lockedPadrao": 0,
  "spendablePadrao": 500
}

Na API pública, balance expõe apenas campos *Padrao. Use spendablePadrao como saldo utilizável para saques e remove-balance. Exclusão (delete) exige saldo Padr?o 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 lockedPadrao — não usa blockedAmount da conta principal. MED em PIX da conta principal segue o fluxo normal na main. Veja também Disputas MED.
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_PADRAO_DEPOSIT`
PIX saída (transferência)	`PIX_PADRAO_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

​Portal Wallet

​O que o operador vê

​Habilitar login na subconta (API key)

​Na criação da subconta

​Subconta já existente (sem login)

​Consultar status do portal (API key)

​Outras rotas de gestão (API key)

​Alternativa: dashboard merchant

​Login do operador (wallet)

​Relação com a API pública

​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

Portal Wallet

O que o operador vê

Habilitar login na subconta (API key)

Na criação da subconta

Subconta já existente (sem login)

Consultar status do portal (API key)

Outras rotas de gestão (API key)

Alternativa: dashboard merchant

Login do operador (wallet)

Relação com a API pública

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