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

# Manage and monitor cards

> List cards, block and unblock them, read transactions, and handle card webhooks

Once cards are issued, you'll list them, freeze and unfreeze them, and reconcile their transactions. This guide covers the card lifecycle and the webhooks that tell you when something happens on a card.

## List cards

Cards are paginated. Pass `limit` and the `next` cursor from the previous response to page through results.

List the cards in a single wallet:

```bash theme={null}
curl 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards?limit=20' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'
```

Or list every card across an account (all wallets):

```bash theme={null}
curl 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/cards?limit=20' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'
```

Both return `{ "items": [...], "next": "<cursor>" }`. Each item carries the masked PAN, `status`, and your `customFields`. To read the full PAN and CVV of a specific card, call the details endpoint — see [Issue virtual cards](/guides/issue-virtual-cards#step-2-read-the-card-details).

Reference: [`GET .../wallets/{walletId}/cards`](/api-reference/banking/cards/realms-organizations-accounts-wallets-cards) · [`GET .../accounts/{accountId}/cards`](/api-reference/banking/cards/realms-organizations-accounts-cards)

## Block and unblock a card

Blocking a card sets its `status` to `BLOCKED` and stops new authorizations without destroying the card. Unblocking restores it to `ACTIVE`.

```bash theme={null}
# Block
curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}/block' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

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

Reference: [`POST .../cards/{cardId}/block`](/api-reference/banking/cards/realms-organizations-accounts-wallets-cards-block) · [`POST .../cards/{cardId}/unblock`](/api-reference/banking/cards/realms-organizations-accounts-wallets-cards-unblock)

## Read a card's transactions

List the transactions on a card within a date range. Results are paginated with the same `next` cursor pattern.

```bash theme={null}
curl 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}/transactions?startDate=2026-01-01&endDate=2026-01-31' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'
```

Each item describes the authorization and the merchant. Useful fields:

| Field                                                               | Meaning                                                             |
| ------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `billingAmount`                                                     | Amount in your currency (centavos, BRL).                            |
| `billingCurrency`                                                   | Always `986` (BRL, ISO 4217).                                       |
| `financialImpactType`                                               | `DEBIT`, `CREDIT`, or `NONE`.                                       |
| `cardTransaction.txnAmount` / `txnCurrency`                         | Original transaction amount and currency (for international spend). |
| `cardTransaction.mcc`                                               | Merchant category code.                                             |
| `cardTransaction.merchantName` / `merchantCity` / `merchantCountry` | Where the charge happened.                                          |
| `responseCode`                                                      | `0` for an approved authorization.                                  |

Reference: [`GET .../cards/{cardId}/transactions`](/api-reference/banking/cards/realms-organizations-accounts-wallets-cards-transactions)

<Tip>
  To list transactions across a whole wallet (cards, PIX, boleto, and transfers together), use the wallet transactions endpoint described in [Wallets for your customers](/guides/wallets#read-transactions).
</Tip>

## Card webhooks

Instead of polling, subscribe to webhooks to react to card activity in real time. All Portão 3 webhooks share the same envelope — see [Receive webhooks](/guides/webhooks) for the delivery model and how to deduplicate.

### A transaction happened on a card

`CARD_TRANSACTION` (source `WALLET`) fires when a card is charged; a refused authorization fires `CARD_TRANSACTION_REFUSED`. The `payload` mirrors a transaction item: `cardId`, `billingAmount`, `balanceCategory`, and the nested `cardTransaction` with the merchant details and `mcc`.

### A card needs a verification code (tokenization)

When a cardholder adds the card to a device wallet (Apple Pay, Google Pay), the issuer sends an activation code you must relay to the cardholder:

```json theme={null}
{
  "source": "WALLET",
  "event": "CARDLESS_PAYMENT_ACTIVATION_CODE_EVENT",
  "payload": {
    "walletId": "...",
    "cardId": "...",
    "activationCode": "976486",
    "deviceWalletName": "APPLE PAY"
  }
}
```

Forward `activationCode` to the cardholder so they can finish validating the card in their device wallet.

## Next steps

<CardGroup cols={2}>
  <Card title="Receive webhooks" icon="bell" href="/guides/webhooks">
    The notification envelope and the full event catalog.
  </Card>

  <Card title="Control card spending" icon="sliders" href="/guides/card-spending-controls">
    Limits, rules, and available balance.
  </Card>
</CardGroup>