Criar subconta

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"
}

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)

Envie portalEmail 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-data com data (JSON) + registrationDocument. JSON puro para PJ retorna erro. Em PJ, portalEmail e portalPassword vão dentro do JSON do campo data.
Portal Wallet: mesma permissão subaccount/create; para gestão depois use permissões subaccount/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

X-API-Key

string

header

required

Chave gp_live_... criada em Integrações → Chaves de API no dashboard.

Body

personType

enum<string>

required

Available options:

PF,

PJ

fullName

string

required

Nome completo do titular (representante em PJ).

Maximum string length: 200

cpf

string

required

CPF com 11 dígitos (somente números ou formatado).

birthDate

string<date>

required

Data de nascimento (YYYY-MM-DD).

postalCode

string

required

CEP com 8 dígitos.

externalReference

string

required

Maximum string length: 64

filiation

string

Opcional. Filiação (nome dos pais ou equivalente).

Maximum string length: 500

monthlyIncome

number

Opcional. Renda mensal em reais.

Required range: x >= 0

profession

string

Opcional. Profissão.

Maximum string length: 120

cnpj

string

Obrigatório se personType=PJ.

legalName

string

Razão social (PJ).

Maximum string length: 200

website

string

Site da empresa (PJ).

Maximum string length: 500

portalEmail

string<email>

Opcional. E-mail de login no Portal Wallet (wallet.goatpay.com.br).

portalPassword

string

Obrigatório se portalEmail for informado. Senha inicial do operador.

Minimum string length: 8

name

string

deprecated

Ignorado; use fullName (PF) ou legalName (PJ). Resposta retorna name derivado.

Response

Operação concluída.

success

boolean

required

Example:

true

message

string

required

Example:

"Operação concluída com sucesso"

data

object

required

requestId

string

Guia Consultar

Introdução

Webhooks

PIX

Conta

Loja

Subcontas

Campos comuns (PF e PJ)

Portal Wallet (opcional, na mesma requisição)

Campos adicionais (PJ)

Authorizations

Body

Response

​Campos comuns (PF e PJ)

​Portal Wallet (opcional, na mesma requisição)

​Campos adicionais (PJ)

Authorizations

Body

Response

Campos comuns (PF e PJ)

Portal Wallet (opcional, na mesma requisição)

Campos adicionais (PJ)