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 pelo seu _id.
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 ao menos uma condição. 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. O _id da resposta é o ID da regra — coloque-o nos ruleIds 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.
`cardType`	O cartão usado: `embossed_card` (físico) ou `digital_card` (virtual).

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 os dois _ids a partir de um mesmo limite (regras em um limite são OR).

Com EQUALS/NOT_EQUAL, um mcc deve ser um código de categoria de estabelecimento de quatro dígitos conhecido e um cardType deve ser embossed_card ou digital_card — outros valores são rejeitados. Condições de país (merchantCountry, acquiringCountryCode) ainda não são suportadas: uma regra que as usa pode não ser aplicada como escrita.

Atualize uma regra depois com o endpoint PUT, referenciando seu _id como cardLimitRuleId. Envie a regra inteira: rules substitui todas as condições, e a mudança vale na hora para todo limite que a usa. 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