Limits

Customer Limits

In this section, you will learn how to configure and query transaction limits (cash-in and cash-out) for your customers using the PixToPay API.

Available Endpoint

  • Production: https://api.pixtopay.com.br/v2/limits

Create or update limit

Configure or update transaction limits for a specific customer. If a limit already exists for the customer, it will be updated.

Route

POST /v2/limits

Headers

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

Body Parameters

ParameterTypeRequiredDescription
document_numberstringYesCustomer document number (CPF — 11 digits)
typestringYesLimit type: "cashin" (charges) or "cashout" (payments)
mechanismstringYesLimit mechanism: "amount" (value) or "quantity" (count)
amountnumberYes*Limit amount in reais (required if mechanism = "amount")
quantityintegerYes*Transaction count limit (required if mechanism = "quantity")
detailsstringNoNote/reason for the limit (maximum 4096 characters)

* Use amount for value-based limits or quantity for transaction-count limits

Request example — value limit

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": "Limit for VIP customer"
}'

Request example — quantity limit

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": "Limit of 50 charges per day"
}'

Response 200 - Success

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

Response Fields

ParameterTypeDescription
document_numberstringCustomer document number
typestringConfigured limit type
mechanismstringLimit mechanism
amountnumberLimit amount (if mechanism = "amount")
quantityintegerTransaction limit (if mechanism = "quantity")
detailsstringNote/reason for the limit
created_atstringLimit creation date and time
updated_atstringLast update date and time

Response 400 - Invalid value

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

Response 400 - Invalid type

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

Query customer limit

Query the limit configured for a specific customer.

Route

GET /v2/limits

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

ParameterTypeRequiredDescription
document_numberstringYesCustomer document number (CPF)
typestringYesLimit type: "cashin" or "cashout"

Request example

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

Response 200 - Success

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

Response 400 - Invalid document

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

Response 404 - Limit not found

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

Limit Types

1. Value limit (amount)

  • Use: Caps the maximum amount per transaction
  • Example: Customer can make payments up to R$ 10,000.00
  • Application: Each individual transaction is checked against this limit

2. Quantity limit (quantity)

  • Use: Caps the number of transactions in a period
  • Example: Customer can create up to 50 charges per day
  • Application: The counter resets daily (midnight UTC-3)

Operation Types

Cash-in (PIX charges)

  • type: "cashin"
  • Controls: Limits for creating PIX charges
  • Application: Checked when creating a new charge via POST /v2/pix

Cash-out (payments)

  • type: "cashout"
  • Controls: Limits for PIX payments
  • Application: Checked when creating a new payment via POST /v2/payout/pix or POST /v2/payout

How Limits Are Applied

1. Automatic check

When a customer attempts a transaction, the API automatically:

  1. Checks whether a limit is configured
  2. Compares against the defined limit
  3. Approves or rejects the transaction

2. Value limits

Transaction: R$ 15,000.00
Limit: R$ 20,000.00
Result: ✅ Approved
Transaction: R$ 25,000.00
Limit: R$ 20,000.00
Result: ❌ Rejected (exceeds limit)

3. Quantity limits

Transactions today: 45
Limit: 50
Result: ✅ Approved (5 remaining)
Transactions today: 50
Limit: 50
Result: ❌ Rejected (limit reached)

Use Cases

1. Risk control for new customers

// Set a low initial limit for new customers
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: "Initial limit — new customer",
    }),
  });
}

2. VIP limit upgrade

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: "VIP customer — increased limit",
    }),
  });
}

3. Check limit before processing

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; // No limit configured
}

Important Notes

  • 🔄 Updates: POST with the same document_number and type updates the existing limit
  • 📊 Independence: Cash-in and cash-out limits are independent
  • ⏰ Daily reset: Quantity limits reset at midnight (UTC-3)
  • 🚫 No limit: If no limit is configured, there is no restriction
  • 📝 Audit: The details field helps with traceability and compliance
  • 💰 Positive values: Only positive values are accepted

Best Practices

1. Configure limits for all new customers

Protect your business with conservative limits initially

2. Monitor and adjust

Review and adjust limits based on customer behavior

3. Use the details field

Document the reason for each limit for audit purposes

4. Combine mechanisms

Configure both value and quantity limits when needed

5. Notify customers

Inform customers when limits are reached for a better experience

BalanceDeposit Volumes