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 Santos",
"cpf": "52998224725",
"birthDate": "1990-05-15",
"postalCode": "01310100",
"externalReference": "titular-maria"
}'
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 Santos",
"cpf": "52998224725",
"birthDate": "1990-05-15",
"postalCode": "01310100",
"externalReference": "titular-maria",
"portalEmail": "operador@empresa.com",
"portalPassword": "SenhaForte!123"
}'
curl -X POST 'https://api.goatpay.com.br/v1/subaccount/create' \
-H 'X-API-Key: gp_live_SUA_CHAVE' \
-F 'data={"personType":"PJ","fullName":"Carlos Souza","cpf":"52998224725","birthDate":"1985-03-20","postalCode":"01310100","cnpj":"11222333000181","legalName":"Loja Parceiro LTDA","website":"https://loja.exemplo.com","externalReference":"loja-parceiro-a","portalEmail":"operador@empresa.com","portalPassword":"SenhaForte!123"};type=application/json' \
-F 'registrationDocument=@contrato-social.pdf'
{
"success": true,
"message": "Subconta criada",
"data": {
"id": "clx_subconta",
"name": "Maria Silva Santos",
"personType": "PF",
"cpf": "52998224725",
"birthDate": "1990-05-15",
"externalReference": "titular-maria",
"status": "ACTIVE",
"lockMode": "NONE",
"balance": {
"availablePadrao": 0,
"pendingPadrao": 0,
"lockedPadrao": 0,
"spendablePadrao": 0
},
"limits": null
},
"requestId": "req_abc"
}
Gerenciar
Criar subconta
Cria subconta merchant (KYC PF/PJ) e, opcionalmente, já habilita o Portal Wallet com e-mail e senha.
POST
/
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 Santos",
"cpf": "52998224725",
"birthDate": "1990-05-15",
"postalCode": "01310100",
"externalReference": "titular-maria"
}'
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 Santos",
"cpf": "52998224725",
"birthDate": "1990-05-15",
"postalCode": "01310100",
"externalReference": "titular-maria",
"portalEmail": "operador@empresa.com",
"portalPassword": "SenhaForte!123"
}'
curl -X POST 'https://api.goatpay.com.br/v1/subaccount/create' \
-H 'X-API-Key: gp_live_SUA_CHAVE' \
-F 'data={"personType":"PJ","fullName":"Carlos Souza","cpf":"52998224725","birthDate":"1985-03-20","postalCode":"01310100","cnpj":"11222333000181","legalName":"Loja Parceiro LTDA","website":"https://loja.exemplo.com","externalReference":"loja-parceiro-a","portalEmail":"operador@empresa.com","portalPassword":"SenhaForte!123"};type=application/json' \
-F 'registrationDocument=@contrato-social.pdf'
{
"success": true,
"message": "Subconta criada",
"data": {
"id": "clx_subconta",
"name": "Maria Silva Santos",
"personType": "PF",
"cpf": "52998224725",
"birthDate": "1990-05-15",
"externalReference": "titular-maria",
"status": "ACTIVE",
"lockMode": "NONE",
"balance": {
"availablePadrao": 0,
"pendingPadrao": 0,
"lockedPadrao": 0,
"spendablePadrao": 0
},
"limits": null
},
"requestId": "req_abc"
}
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 Santos",
"cpf": "52998224725",
"birthDate": "1990-05-15",
"postalCode": "01310100",
"externalReference": "titular-maria"
}'
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 Santos",
"cpf": "52998224725",
"birthDate": "1990-05-15",
"postalCode": "01310100",
"externalReference": "titular-maria",
"portalEmail": "operador@empresa.com",
"portalPassword": "SenhaForte!123"
}'
curl -X POST 'https://api.goatpay.com.br/v1/subaccount/create' \
-H 'X-API-Key: gp_live_SUA_CHAVE' \
-F 'data={"personType":"PJ","fullName":"Carlos Souza","cpf":"52998224725","birthDate":"1985-03-20","postalCode":"01310100","cnpj":"11222333000181","legalName":"Loja Parceiro LTDA","website":"https://loja.exemplo.com","externalReference":"loja-parceiro-a","portalEmail":"operador@empresa.com","portalPassword":"SenhaForte!123"};type=application/json' \
-F 'registrationDocument=@contrato-social.pdf'
{
"success": true,
"message": "Subconta criada",
"data": {
"id": "clx_subconta",
"name": "Maria Silva Santos",
"personType": "PF",
"cpf": "52998224725",
"birthDate": "1990-05-15",
"externalReference": "titular-maria",
"status": "ACTIVE",
"lockMode": "NONE",
"balance": {
"availablePadrao": 0,
"pendingPadrao": 0,
"lockedPadrao": 0,
"spendablePadrao": 0
},
"limits": null
},
"requestId": "req_abc"
}
Campos comuns (PF e PJ)
string
required
PF ou PJ.string
required
Nome completo do titular (representante legal em PJ).
string
required
CPF válido (11 dígitos).
string
required
Data de nascimento (
YYYY-MM-DD).string
required
CEP (8 dígitos).
string
required
Referência única do seu sistema (máx. 64). Obrigatória na API pública.
Portal Wallet (opcional, na mesma requisição)
EnvieportalEmail e portalPassword junto com o cadastro KYC. A subconta e o login em wallet.goatpay.com.br ficam ativos na hora — sem e-mail de confirmação e sem chamar POST /subaccount/portal/setup depois.
string
E-mail de login do operador no Portal Wallet. Se informado,
portalPassword é obrigatório na mesma requisição.string
Senha inicial do operador (mín. 8 caracteres, maiúscula, minúscula, número e símbolo). Obrigatório junto com
portalEmail.portalEmail sem portalPassword retorna erro 400. Para subcontas já criadas sem portal, use portal/setup.Campos adicionais (PJ)
string
required
CNPJ válido (14 dígitos). Obrigatório se
personType = PJ.string
required
Razão social. O campo
name na resposta usa este valor.string
required
URL do site (com ou sem
https://).file
required
Somente multipart. Comprovante de inscrição ou contrato social (PDF, JPG, PNG ou WEBP, máx. 8 MB). Campo do formulário:
registrationDocument. O JSON vai no campo data.- PF: envie
Content-Type: application/json. - PJ: envie
multipart/form-datacomdata(JSON) +registrationDocument. JSON puro para PJ retorna erro. Em PJ,portalEmaileportalPasswordvão dentro do JSON do campodata. - Portal Wallet: mesma permissão
subaccount/create; para gestão depois use permissõessubaccount/portal/*(guia). - Subcontas criadas antes do KYC permanecem válidas; os novos campos são exigidos apenas em novas criações.
- No dashboard, use Gerenciar subconta para movimentar saldo, limites, bloqueios e pricing sem chamar a API manualmente.
Authorizations
Chave gp_live_... criada em Integrações → Chaves de API no dashboard.
Body
application/jsonmultipart/form-data
Available options:
PF, PJ Nome completo do titular (representante em PJ).
Maximum string length:
200CPF com 11 dígitos (somente números ou formatado).
Data de nascimento (YYYY-MM-DD).
CEP com 8 dígitos.
Maximum string length:
64Opcional. Filiação (nome dos pais ou equivalente).
Maximum string length:
500Opcional. Renda mensal em reais.
Required range:
x >= 0Opcional. Profissão.
Maximum string length:
120Obrigatório se personType=PJ.
Razão social (PJ).
Maximum string length:
200Site da empresa (PJ).
Maximum string length:
500Opcional. E-mail de login no Portal Wallet (wallet.goatpay.com.br).
Obrigatório se portalEmail for informado. Senha inicial do operador.
Minimum string length:
8Ignorado; use fullName (PF) ou legalName (PJ). Resposta retorna name derivado.