> ## Documentation Index
> Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Controlar gastos do cartão

> Anexe limites de gasto e regras de gasto aos cartões, e consulte o saldo disponível

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`.

```mermaid theme={null}
flowchart LR
  txn[Card transaction] --> limit[Card limit<br/>amount + window]
  limit -->|any rule matches OR| ruleA[Rule A<br/>all conditions AND]
  limit -->|any rule matches OR| ruleB[Rule B<br/>all conditions AND]
```

`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.

```bash theme={null}
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`](/api-reference/banking/cards/realms-organizations-accounts-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.

```bash theme={null}
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'
```

```json theme={null}
[
  {
    "_id": "68910e1ff339631b6222d9b6",
    "name": "Teste",
    "amount": 500,
    "status": "ACTIVE",
    "availableAmount": 500,
    "pendingAmount": 0
  }
]
```

Referência: [`GET .../cards/{cardId}/card-limit`](/api-reference/banking/cards/realms-organizations-accounts-wallets-cards-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).

```bash theme={null}
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}`](/api-reference/banking/cards/realms-organizations-accounts-card-limit-2)

## 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`:

```bash theme={null}
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                   |

<Note>
  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.
</Note>

### 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:

```json theme={null}
{
  "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 `ruleId`s a partir de um mesmo limite (regras em um limite são `OR`).

<Warning>
  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.
</Warning>

Atualize uma regra depois com o endpoint PUT, referenciando seu `cardLimitRuleId`.

Referência: [`POST .../card-limit-rule`](/api-reference/banking/cards/realms-organizations-accounts-card-limit-rule-1) · [`PUT .../card-limit-rule/{cardLimitRuleId}`](/api-reference/banking/cards/realms-organizations-accounts-card-limit-rule-3)

## Próximos passos

<CardGroup cols={2}>
  <Card title="Emitir cartões virtuais" icon="credit-card" href="/guides/issue-virtual-cards">
    Crie um cartão e leia seu PAN e CVV.
  </Card>

  <Card title="Gerenciar e monitorar cartões" icon="list" href="/guides/manage-cards">
    Bloqueie, desbloqueie e leia o histórico de transações de um cartão.
  </Card>
</CardGroup>