Skip to main content
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ê

RecursoDescrição
DashboardSaldo, métricas do dia, gráfico de volume e atividade recente
Depositar / TransferirPIX na subconta (trilho Padrão)
Extrato e resumoMovimentações filtradas pela subconta
Disputas (MED)MEDs vinculados a transações da subconta
ContaSegurança, 2FA, senha

​
Habilitar login na subconta (API key)

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"
  }'
CampoTipoObrigatórioDescrição
portalEmailstringSe quiser portalE-mail de login no Portal Wallet
portalPasswordstringSim, se informar portalEmailSenha 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.

​
Subconta já existente (sem login)

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"
  }'
CampoObrigatórioDescrição
id ou externalReferenceSim (um dos dois)Identifica a subconta
emailSimE-mail de login (único na plataforma para portal)
passwordSimSenha 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:
EstadoSignificado
noneSem login de portal configurado
activeE-mail e senha cadastrados; operador pode entrar
disabledPortal revogado pelo merchant
pending_passwordLegado — reconfigure com portal/setup
invite_pendingLegado — reconfigure com portal/setup
pending_verificationLegado — contas antigas antes da remoção da verificação por e-mail

​
Outras rotas de gestão (API key)

MétodoRotaPermissãoUso
POST/v1/subaccount/portal/update-emailsubaccount/portal/update-emailAlterar e-mail do operador
POST/v1/subaccount/portal/revokesubaccount/portal/revokeRevogar acesso ao portal
POST/v1/subaccount/portal/reset-2fasubaccount/portal/reset-2faResetar 2FA do operador

​
Alternativa: dashboard merchant (JWT)

As mesmas operações estão disponíveis no app em Contas → Subcontas → Gerenciar subconta → aba Portal, ou via JWT de usuário:
MétodoRota
GET/account/subaccounts/portal
POST/account/subaccounts/portal/setup
POST/account/subaccounts/portal/update-email
POST/account/subaccounts/portal/revoke
POST/account/subaccounts/portal/reset-2fa
A rota POST /account/subaccounts/portal/invite foi descontinuada. Use sempre setup com e-mail e senha.

​
Autenticação do operador (wallet)

RotaDescrição
POST /auth/wallet/loginLogin com e-mail e senha cadastrados pelo merchant
POST /auth/wallet/forgot-password / reset-passwordRecuperação de senha
GET /wallet/dashboardDados do dashboard (JWT portal)
O JWT do portal usa principalType: subaccount_portal e escopa todas as rotas /wallet/* à subconta vinculada.

​
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.
Veja também o guia de subcontas.