Skip to main content
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"
  }'

{
  "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": {
      "availableWhite": 0,
      "pendingWhite": 0,
      "lockedWhite": 0,
      "spendableWhite": 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"
  }'

{
  "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": {
      "availableWhite": 0,
      "pendingWhite": 0,
      "lockedWhite": 0,
      "spendableWhite": 0
    },
    "limits": null
  },
  "requestId": "req_abc"
}

​
Campos comuns (PF e PJ)

​
personType
string
required
PF ou PJ.
​
fullName
string
required
Nome completo do titular (representante legal em PJ).
​
cpf
string
required
CPF válido (11 dígitos).
​
birthDate
string
required
Data de nascimento (YYYY-MM-DD).
​
postalCode
string
required
CEP (8 dígitos).
​
externalReference
string
required
Referência única do seu sistema (máx. 64). Obrigatória na API pública.

​
Campos adicionais (PJ)

​
cnpj
string
required
CNPJ válido (14 dígitos). Obrigatório se personType = PJ.
​
legalName
string
required
Razão social. O campo name na resposta usa este valor.
​
website
string
required
URL do site (com ou sem https://).
​
registrationDocument
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.
  • 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
​
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:

"Pagamento PIX criado com sucesso"

​
data
object
required
​
requestId
string