Controlar gastos do cartão

Toda cobrança em um cartão é autorizada contra um limite de cartão — um valor, uma janela de validade e as regras de gasto que ele pode usar. As regras permitem aprovar ou bloquear transações por categoria de estabelecimento, valor, país, horário e mais. Este guia cobre anexar um limite a um cartão existente, definir regras de gasto, remover um limite e ler quanto ainda está disponível.

Como os controles de gasto se encaixam

Dois objetos trabalham juntos para decidir se uma transação de cartão é aprovada:

Uma regra de limite de cartão descreve onde e como um cartão pode gastar. É um conjunto nomeado de condições — cada condição testa um atributo da transação (a categoria do estabelecimento, o valor, o país, o horário, …). Todas as condições em uma regra devem casar para que a regra permita uma transação (AND). Uma regra é reutilizável: crie-a uma vez e referencie-a a partir de muitos limites. Cada regra que você cria retorna um ruleId.
Um limite de cartão autoriza gastos: limita um amount (em centavos), é válido entre startDate e endDate, aplica-se a um ou mais cardIds e referencia um ou mais ruleIds. Uma transação é permitida quando cai dentro do valor e da janela e qualquer uma das regras referenciadas casa (OR).

Em resumo: condições dentro de uma regra são AND; regras dentro de um limite são OR. FLEX_INTERNATIONAL é um padrão permissivo que você pode passar como ruleId enquanto começa, e depois substituir pelas suas próprias regras (definidas abaixo).

Adicionar um limite a um cartão existente

Use isto antes de cada cobrança em um cartão reutilizável, ou sempre que quiser recarregar o valor autorizado de um cartão.

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/card-limit' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Rule",
    "amount": 3500,
    "startDate": "2026-07-01",
    "endDate": "2026-07-01",
    "cardIds": ["661d6bdbea0c92b33803a8ad"],
    "ruleIds": ["FLEX_INTERNATIONAL"]
  }'

Um 201 confirma que o limite foi anexado. amount é em centavos; defina startDate/endDate para a data de hoje para uma cobrança no mesmo dia. Referência: POST .../card-limit

Consultar o valor disponível

Leia os limites ativos de um cartão para ver quanto ainda resta para gastar. availableAmount diminui à medida que as transações são liquidadas; pendingAmount reflete gastos autorizados mas ainda não liquidados.

curl 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}/card-limit' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

[
  {
    "_id": "68910e1ff339631b6222d9b6",
    "name": "Teste",
    "amount": 500,
    "status": "ACTIVE",
    "availableAmount": 500,
    "pendingAmount": 0
  }
]

Referência: GET .../cards/{cardId}/card-limit

Remover um limite

Exclua um limite pelo seu cardLimitId para impedir novas autorizações contra ele (por exemplo, para encerrar um cartão reutilizável).

curl -X DELETE \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/card-limit/{cardLimitId}' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

Um 204 confirma a remoção. Referência: DELETE .../card-limit/{cardLimitId}

Definir uma regra

Uma regra é uma description mais um array rules de condições. Cada condição testa uma property da transação contra um valor comparative usando um operator. Todas as condições devem casar para que a regra permita uma transação. A resposta retorna um ruleId (sob external.ruleId e como o _id do documento) que você referencia a partir de um limite de cartão. Esta regra de condição única permite tudo exceto a categoria de estabelecimento 3001:

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/card-limit-rule' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "BLOCK_MCC_3001",
    "rules": [
      { "property": "mcc", "operator": "NOT_EQUAL", "comparative": "3001" }
    ]
  }'

Propriedades da transação

Uma condição pode testar qualquer uma destas propriedades:

Propriedade	O que testa
`mcc`	Código da categoria do estabelecimento.
`merchantId`	Identificador do estabelecimento.
`merchantName`	Nome do estabelecimento.
`merchantCity`	Cidade do estabelecimento.
`merchantCountry`	País do estabelecimento.
`acquiringCountryCode`	País do adquirente.
`billingAmount`	Valor cobrado, em centavos.
`txnCurrency`	Moeda da transação.
`msgType`	Tipo de mensagem da autorização.
`txnType`	Tipo da transação.
`effectiveAtHour`	Hora do dia em que a transação ocorreu.
`effectiveAtWeekday`	Dia da semana em que a transação ocorreu.

Operadores

Operador	Significado	Formato de `comparative`
`EQUALS` / `NOT_EQUAL`	Igual a / diferente de	um único valor
`GREATER_THAN` / `GREATER_THAN_OR_EQUAL`	Maior que (ou igual)	um único número
`LESS_THAN` / `LESS_THAN_OR_EQUAL`	Menor que (ou igual)	um único número
`BETWEEN` / `NOT_BETWEEN`	Dentro / fora de um intervalo	dois valores, `"min, max"`
`IN` / `NOT_IN`	Em / não em uma lista	lista separada por vírgulas
`CONTAINS` / `NOT_CONTAINS`	Correspondência de substring	um único valor
`MATCHES` / `NOT_MATCHES`	Correspondência de expressão regular	uma regex

Cada teste expõe tanto a forma positiva quanto a negada (EQUALS / NOT_EQUAL, IN / NOT_IN, …), então você não precisa de uma flag “negar” separada — escolha o operador que expresse sua intenção.

Uma regra com múltiplas condições

Como as condições são combinadas com AND, esta regra permite apenas compras em mercados (MCC 5411) abaixo de R$ 500,00:

{
  "description": "GROCERY_UNDER_500",
  "rules": [
    { "property": "mcc", "operator": "EQUALS", "comparative": "5411" },
    { "property": "billingAmount", "operator": "LESS_THAN", "comparative": "50000" }
  ]
}

Para expressar “mercado ou farmácia”, use o operador IN em uma única condição ("comparative": "5411, 5912"), ou crie duas regras separadas e referencie ambos os ruleIds a partir de um mesmo limite (regras em um limite são OR).

Quando property for mcc com EQUALS/NOT_EQUAL, comparative deve ser um código de categoria de estabelecimento válido. Quando property for merchantCountry ou acquiringCountryCode com EQUALS/NOT_EQUAL, comparative deve ser um código ISO de país válido. Valores inválidos são rejeitados.

Atualize uma regra depois com o endpoint PUT, referenciando seu cardLimitRuleId. Referência: POST .../card-limit-rule · PUT .../card-limit-rule/{cardLimitRuleId}

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

Controlar gastos do cartão

Como os controles de gasto se encaixam

Adicionar um limite a um cartão existente

Consultar o valor disponível

Remover um limite

Definir uma regra

Propriedades da transação

Operadores

Uma regra com múltiplas condições

Próximos passos

Emitir cartões virtuais

Gerenciar e monitorar cartões

​Como os controles de gasto se encaixam

​Adicionar um limite a um cartão existente

​Consultar o valor disponível

​Remover um limite

​Definir uma regra

​Propriedades da transação

​Operadores

​Uma regra com múltiplas condições

​Próximos passos

Emitir cartões virtuais

Gerenciar e monitorar cartões

Como os controles de gasto se encaixam

Adicionar um limite a um cartão existente

Consultar o valor disponível

Remover um limite

Definir uma regra

Propriedades da transação

Operadores

Uma regra com múltiplas condições

Próximos passos