Limites

Limites de Clientes

Nesta seção, você aprenderá como configurar e consultar limites de transações (cash-in e cash-out) para seus clientes usando a API PixToPay.

Endpoint Disponível

  • Produção: https://api.pixtopay.com.br/v2/limits

Criar ou atualizar limite

Configure ou atualize limites de transações para um cliente específico. Se já existir um limite para o cliente, ele será atualizado.

Route

POST /v2/limits

Headers

{
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

Body Parameters

ParâmetroTipoObrigatórioDescrição
document_numberstringSimNúmero do documento do cliente (CPF - 11 dígitos)
typestringSimTipo de limite: "cashin" (cobranças) ou "cashout" (pagamentos)
mechanismstringSimMecanismo do limite: "amount" (valor) ou "quantity" (quantidade)
amountnumberSim*Valor limite em reais (obrigatório se mechanism = "amount")
quantityintegerSim*Quantidade limite de transações (obrigatório se mechanism = "quantity")
detailsstringNãoAnotação/motivo do limite (máximo 4096 caracteres)

* Use amount para limites por valor ou quantity para limites por quantidade de transações

Exemplo de requisição - Limite por valor:

curl --location 'https://api.pixtopay.com.br/v2/limits' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "document_number": "12345678900",
    "type": "cashout",
    "mechanism": "amount",
    "amount": 20000,
    "details": "Limite para cliente VIP"
}'

Exemplo de requisição - Limite por quantidade:

curl --location 'https://api.pixtopay.com.br/v2/limits' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "document_number": "12345678900",
    "type": "cashin",
    "mechanism": "quantity",
    "quantity": 50,
    "details": "Limite de 50 cobranças por dia"
}'

Resposta 200 - Sucesso:

{
  "document_number": "12345678900",
  "type": "cashout",
  "mechanism": "amount",
  "details": "Limite para cliente VIP",
  "amount": 20000,
  "created_at": "2025-03-12T23:45:11.000Z",
  "updated_at": "2025-03-13T00:56:52.000Z"
}

Campos da Resposta

ParâmetroTipoDescrição
document_numberstringNúmero do documento do cliente
typestringTipo de limite configurado
mechanismstringMecanismo do limite
amountnumberValor limite (se mechanism = "amount")
quantityintegerQuantidade limite (se mechanism = "quantity")
detailsstringAnotação/motivo do limite
created_atstringData e hora de criação do limite
updated_atstringData e hora da última atualização

Resposta 400 - Valor inválido:

{
  "type": "ValidationError",
  "message": "body.amount must be a positive number"
}

Resposta 400 - Tipo inválido:

{
  "type": "ValidationError",
  "message": "body.type must be one of cashin or cashout"
}

Consultar limite de cliente

Consulte o limite configurado para um cliente específico.

Route

GET /v2/limits

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

ParâmetroTipoObrigatórioDescrição
document_numberstringSimNúmero do documento do cliente (CPF)
typestringSimTipo de limite: "cashin" ou "cashout"

Exemplo de requisição:

curl --location 'https://api.pixtopay.com.br/v2/limits?document_number=12345678900&type=cashout' \
--header 'Authorization: API_KEY'

Resposta 200 - Sucesso:

{
  "document_number": "12345678900",
  "type": "cashout",
  "mechanism": "amount",
  "amount": 30000,
  "details": "Limite para cliente VIP",
  "created_at": "2025-03-12T22:58:33.000Z",
  "updated_at": "2025-03-12T22:58:33.000Z"
}

Resposta 400 - Documento inválido:

{
  "type": "ValidationError",
  "message": "query.document_number is invalid"
}

Resposta 404 - Limite não encontrado:

{
  "message": "No limit found for this customer"
}

Tipos de Limite

1. Limite por Valor (amount)

  • Uso: Restringe o valor máximo por transação
  • Exemplo: Cliente pode fazer pagamentos de até R$ 10.000,00
  • Aplicação: Cada transação individual é verificada contra este limite

2. Limite por Quantidade (quantity)

  • Uso: Restringe a quantidade de transações em um período
  • Exemplo: Cliente pode fazer até 50 cobranças por dia
  • Aplicação: Contador é resetado diariamente (meia-noite UTC-3)

Tipos de Operação

Cash-in (Cobranças PIX)

  • type: "cashin"
  • Controla: Limites para criação de cobranças PIX
  • Aplicação: Verificado ao criar nova cobrança via POST /v2/pix

Cash-out (Pagamentos)

  • type: "cashout"
  • Controla: Limites para pagamentos PIX e TED
  • Aplicação: Verificado ao criar novo pagamento via POST /v2/payout ou POST /v2/payout/pix

Como os Limites São Aplicados

1. Verificação Automática

Quando um cliente tenta realizar uma transação, a API automaticamente:

  1. Verifica se existe limite configurado
  2. Compara com o limite definido
  3. Aprova ou rejeita a transação

2. Limites por Valor

Transação: R$ 15.000,00
Limite: R$ 20.000,00
Resultado: ✅ Aprovada
Transação: R$ 25.000,00
Limite: R$ 20.000,00
Resultado: ❌ Rejeitada (excede limite)

3. Limites por Quantidade

Transações hoje: 45
Limite: 50
Resultado: ✅ Aprovada (ainda tem 5 disponíveis)
Transações hoje: 50
Limite: 50
Resultado: ❌ Rejeitada (limite atingido)

Casos de Uso

1. Controle de risco para novos clientes

// Configurar limite inicial baixo para novos clientes
async function setupNewCustomerLimit(documentNumber) {
  await fetch("https://api.pixtopay.com.br/v2/limits", {
    method: "POST",
    headers: {
      Authorization: "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      document_number: documentNumber,
      type: "cashout",
      mechanism: "amount",
      amount: 1000,
      details: "Limite inicial - cliente novo",
    }),
  });
}

2. Upgrade de limite para clientes VIP

async function upgradeToVipLimit(documentNumber) {
  await fetch("https://api.pixtopay.com.br/v2/limits", {
    method: "POST",
    headers: {
      Authorization: "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      document_number: documentNumber,
      type: "cashout",
      mechanism: "amount",
      amount: 50000,
      details: "Cliente VIP - limite aumentado",
    }),
  });
}

3. Verificar limite antes de processar

async function checkCustomerLimit(documentNumber, transactionAmount) {
  const response = await fetch(
    `https://api.pixtopay.com.br/v2/limits?document_number=${documentNumber}&type=cashout`,
    {
      headers: { Authorization: "YOUR_API_KEY" },
    }
  );
 
  if (response.ok) {
    const limit = await response.json();
    if (limit.mechanism === "amount") {
      return transactionAmount <= limit.amount;
    }
  }
 
  return true; // Sem limite configurado
}

Observações Importantes

  • 🔄 Atualização: Usar POST com mesmo document_number e type atualiza o limite existente
  • 📊 Independência: Limites de cashin e cashout são independentes
  • ⏰ Reset diário: Limites por quantidade são resetados à meia-noite (UTC-3)
  • 🚫 Sem limite: Se não houver limite configurado, não há restrição
  • 📝 Auditoria: Campo details útil para rastreabilidade e compliance
  • 💰 Valores positivos: Apenas valores positivos são aceitos

Boas Práticas

1. Configure limites para todos os clientes novos

Proteja seu negócio com limites conservadores inicialmente

2. Monitore e ajuste

Revise e ajuste limites baseado no comportamento do cliente

3. Use o campo details

Documente o motivo de cada limite para auditoria

4. Combine mecanismos

Configure limites por valor E por quantidade quando necessário

5. Notifique clientes

Avise clientes quando limites forem atingidos para melhor experiência

SaldoVolumes de Depósitos