For the complete documentation index, see llms.txt. This page is also available as Markdown.

Limites da Conta

Endpoints para consultar e alterar os limites diários de transação de uma conta business (PIX e boleto).

Conceitos

Período (period)

Período
Descrição

DAY

Limite do período diurno

NIGHT

Limite do período noturno

Titularidade (isSameOwnership)

Valor
Descrição

true

Mesma titularidade — transferências entre contas do mesmo titular (mesmo CPF/CNPJ)

false

Outras titularidades — transferências para terceiros

O limite de outras titularidades (false) não pode ultrapassar o de mesma titularidade (true) para o mesmo período. Caso ultrapasse, a alteração é rejeitada (400, BNK-0038).

Valores e moeda

  • O campo amount é sempre em reais (BigDecimal). Ex.: 500000 = R$ 500.000,00. Não enviar em centavos.

  • Há um teto de segurança para o valor; valores acima dele retornam 400.

Efetivação

  • Aumento de limite: a alteração é agendada e passa a valer em até 24 horas. Durante esse período, o limite vigente permanece em amount e o novo valor aparece em scheduledAmount.

  • Redução de limite: aplicada imediatamente — o novo valor já vale em amount, sem espera de 24h.

  • Uma nova alteração para o mesmo period + isSameOwnership sobrescreve o agendamento anterior (quando houver) e reinicia o SLA.


GET /v1/accounts/business/{businessId}/limits

Consulta os limites da conta (vigente + agendado), por período e titularidade.

Pré-requisito: Conta deve estar com status ACTIVE.

Path Parameters:

Parâmetro
Tipo
Descrição

businessId

UUID

ID da conta (UUID v4)

Request:

Response — 200 OK:

Campos — Response

Campo
Tipo
Descrição

period

String

DAY ou NIGHT

isSameOwnership

Boolean

true (mesma titularidade) ou false (outras titularidades)

amount

BigDecimal

Limite vigente, em reais. Ex.: 5000.00

scheduledAmount

BigDecimal

Aumento agendado aguardando os 24h, em reais. null quando não há agendamento (inclusive em reduções, que valem na hora)

Status Codes:

Status
Descrição

200 OK

Sucesso

401 Unauthorized

Token inválido ou expirado

403 Forbidden

Conta não pertence ao parceiro

404 Not Found

Conta não encontrada ou sem conta bancária associada


PATCH /v1/accounts/business/{businessId}/limits

Altera o limite diário da conta para um período e titularidade. Atualização parcial: cada chamada altera apenas a fatia informada (period + isSameOwnership) — não é necessário enviar todos os limites. Aumentos são agendados (efetivam em até 24h); reduções valem imediatamente. Idempotente na prática (reenviar o mesmo valor produz o mesmo resultado).

Pré-requisito: Conta deve estar com status ACTIVE.

Path Parameters:

Parâmetro
Tipo
Descrição

businessId

UUID

ID da conta (UUID v4)

Request:

Campos — Request

Campo
Tipo
Obrigatório
Validação

period

String

Sim

Enum: DAY, NIGHT

amount

BigDecimal

Sim

Valor em reais (não centavos). Maior que zero e até o teto permitido. Ex.: 500000 = R$ 500.000,00

isSameOwnership

Boolean

Sim

true = mesma titularidade; false = outras titularidades

Response — 200 OK:

Em aumentos, o novo valor aparece em scheduledAmount e passa a vigorar (amount) em até 24h (exemplo acima). Em reduções, o valor já vale imediatamente em amount e scheduledAmount fica null.

Response — 400 Bad Request (valor inválido / acima do teto):

Exemplo que dispara o erro — alterar outras titularidades (false) para um valor acima do limite vigente de mesma titularidade (no exemplo, mesma titularidade em R$ 500.000 e outras tentando R$ 600.000):

Response — 400 Bad Request (outras titularidades acima da mesma titularidade):

Response — 403 Forbidden (sem acesso a conta):

Status Codes:

Status
Descrição

200 OK

Alteração aceita (aumento efetiva em até 24h; redução imediata)

400 Bad Request

Valor inválido/acima do teto, ou limite de outras titularidades acima do de mesma titularidade

401 Unauthorized

Token inválido ou expirado

403 Forbidden

Conta não pertence ao parceiro

404 Not Found

Conta não encontrada ou sem conta bancária associada

Last updated

Was this helpful?