Criação de conta

Introducao

Este endpoint permite que parceiros autorizados criem contas de usuario programaticamente e ja recebam, na mesma resposta, uma Secret Key pronta para operar o gateway (criar transacoes PIX, consultar status, solicitar saques, etc.).

Acesso restrito. Somente contas com a permissao api_account_creation_enabled ativa podem chamar este endpoint. Solicite a liberacao ao time da LumoPay.

A Secret Key retornada e exibida apenas uma vez. Armazene-a imediatamente em local seguro — nao ha como recupera-la depois (exceto via endpoint de login).

Endpoint — Criar Conta

POST /api/v1/v1-lumopay/accounts

Headers

Header	Valor	Obrigatorio
`x-api-key`	Secret Key do parceiro	Sim
`Content-Type`	`application/json`	Sim

Body (JSON)

Campo	Tipo	Obrigatorio	Descricao
`name`	`string`	Sim	Nome completo (PF) ou razao social (PJ). 3 a 255 caracteres.
`email`	`string`	Sim	E-mail valido. Unico no sistema — nao pode estar em uso por outra conta.
`personType`	`"PF"` \| `"PJ"`	Nao	Tipo de pessoa: `"PF"` para CPF ou `"PJ"` para CNPJ. Se omitido, e detectado automaticamente pelo comprimento do documento (11 = PF, 14 = PJ).
`document`	`string`	Sim	Documento do titular. CPF (11 digitos) para PF ou CNPJ (14 digitos) para PJ. Aceita com ou sem mascara (ex.: `123.456.789-09`, `12.345.678/0001-95`, `12345678909`, `12345678000195`). Validado via algoritmo oficial da Receita Federal.
`cpf`	`string`	Nao	Alias legado. Pode ser usado no lugar de `document` (aceita CPF ou CNPJ). Mantido para compatibilidade com integracoes antigas.
`phone`	`string`	Sim	WhatsApp com DDI + DDD (ex.: `+5511999999999`).

Exemplos de Requisicao

Pessoa Fisica (CPF)

Use quando o titular for uma pessoa natural. document deve ter 11 digitos.

cURL:

Body (JSON):

{
  "name": "Joao Silva",
  "email": "[email protected]",
  "personType": "PF",
  "document": "12345678909",
  "phone": "+5511999999999"
}

Pessoa Juridica (CNPJ)

Use quando o titular for uma empresa. document deve ter 14 digitos e personType deve ser "PJ".

cURL:

Body (JSON):

{
  "name": "Minha Empresa LTDA",
  "email": "[email protected]",
  "personType": "PJ",
  "document": "12345678000195",
  "phone": "+5511999999999"
}

Resposta de Sucesso

200 — Conta criada. Credenciais exibidas uma unica vez.

{
  "status": "success",
  "message": "Conta criada com sucesso.",
  "data": {
    "account_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "name": "Joao Silva",
    "email": "[email protected]",
    "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    "secret_key": "f2aae0788c108dea1d2332ceb2d4c75446fb1db7666280a1c9d0e1f2a3b4c5d6e7f8...",
    "credentials_note": "Guarde sua API Key e Secret Key agora. Elas nao serao exibidas novamente.",
    "set_password_url": "https://app.lumopayment.com/set-password?token=3f9a...c4e1",
    "set_password_expires_at": "2026-05-05T15:42:10.123Z",
    "password_note": "Link de definicao de senha expira em 10 dias e e de uso unico. Exiba-o ao cliente em seu painel."
  }
}

Os campos data.api_key e data.secret_key sao as credenciais de API da nova conta. Guarde-os imediatamente: chamadas subsequentes devolvem as chaves mascaradas.

Respostas de Erro

`400` — Validacao falhou (campos invalidos)

{
  "statusCode": 400,
  "message": "CNPJ invalido",
  "error": "Bad Request"
}

Possiveis mensagens:

"Nome deve ter entre 3 e 255 caracteres"

"E-mail invalido"

"Telefone deve estar no formato +DDI DDD NUMERO (ex: +5511999999999)"

"Documento e obrigatorio (CPF ou CNPJ)"

"CPF deve conter exatamente 11 digitos"

"CNPJ deve conter exatamente 14 digitos"

"CPF invalido"

"CNPJ invalido"

"personType deve ser \"PF\" ou \"PJ\""

`401` — x-api-key ausente, invalida ou desativada

{
  "statusCode": 401,
  "message": "Chave de API invalida ou desativada"
}

`403` — Conta do parceiro sem permissao para criar contas via API

{
  "statusCode": 403,
  "message": "Conta sem permissao para criar contas via API"
}

`409` — E-mail, CPF ou CNPJ ja cadastrado

{
  "statusCode": 409,
  "message": "E-mail ja cadastrado"
}

Possiveis mensagens:

"E-mail ja cadastrado"

"CPF ja cadastrado"

"CNPJ ja cadastrado"

`429` — Rate limit excedido

{
  "statusCode": 429,
  "message": "Muitas requisicoes. Tente novamente em 1 minuto."
}

Introducao#

Endpoint — Criar Conta#

Headers#

Body (JSON)#

Exemplos de Requisicao#

Pessoa Fisica (CPF)#

Pessoa Juridica (CNPJ)#

Resposta de Sucesso#

Respostas de Erro#

400 — Validacao falhou (campos invalidos)#

401 — x-api-key ausente, invalida ou desativada#

403 — Conta do parceiro sem permissao para criar contas via API#

409 — E-mail, CPF ou CNPJ ja cadastrado#

429 — Rate limit excedido#