> ## 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. # Gerenciar e monitorar cartões > Liste cartões, bloqueie e desbloqueie, leia transações e trate webhooks de cartão Uma vez que os cartões forem emitidos, você vai listá-los, congelá-los e descongelá-los, e reconciliar suas transações. Este guia cobre o ciclo de vida do cartão e os webhooks que informam quando algo acontece em um cartão. ## Listar cartões Os cartões são paginados. Passe `limit` e o cursor `next` da resposta anterior para paginar pelos resultados. Liste os cartões em uma única carteira: ```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 ' \ -H 'x-environment: LIVE' ``` Ou liste todos os cartões de uma conta (todas as carteiras): ```bash theme={null} curl 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/cards?limit=20' \ -H 'Authorization: Bearer ' \ -H 'x-environment: LIVE' ``` Ambos retornam `{ "items": [...], "next": "" }`. Cada item carrega o PAN mascarado, o `status` e seus `customFields`. Para ler o PAN completo e o CVV de um cartão específico, chame o endpoint de detalhes — veja [Emitir cartões virtuais](/guides/issue-virtual-cards#step-2-read-the-card-details). Referência: [`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) ## Bloquear e desbloquear um cartão Bloquear um cartão define seu `status` como `BLOCKED` e interrompe novas autorizações sem destruir o cartão. Desbloquear o restaura para `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 ' \ -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 ' \ -H 'x-environment: LIVE' ``` Referência: [`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) ## Ler as transações de um cartão Liste as transações de um cartão dentro de um intervalo de datas. Os resultados são paginados com o mesmo padrão de cursor `next`. ```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 ' \ -H 'x-environment: LIVE' ``` Cada item descreve a autorização e o estabelecimento. Campos úteis: | Campo | Significado | | ------------------------------------------------------------------- | ----------------------------------------------------------------- | | `billingAmount` | Valor na sua moeda (centavos, BRL). | | `billingCurrency` | Sempre `986` (BRL, ISO 4217). | | `financialImpactType` | `DEBIT`, `CREDIT` ou `NONE`. | | `cardTransaction.txnAmount` / `txnCurrency` | Valor original da transação e moeda (para gastos internacionais). | | `cardTransaction.mcc` | Código da categoria do estabelecimento. | | `cardTransaction.merchantName` / `merchantCity` / `merchantCountry` | Onde a cobrança ocorreu. | | `responseCode` | `0` para uma autorização aprovada. | Referência: [`GET .../cards/{cardId}/transactions`](/api-reference/banking/cards/realms-organizations-accounts-wallets-cards-transactions) Para listar transações de uma carteira inteira (cartões, PIX, boleto e transferências juntos), use o endpoint de transações da carteira descrito em [Carteiras para seus clientes](/guides/wallets#read-transactions). ## Webhooks de cartão Em vez de fazer polling, inscreva-se em webhooks para reagir à atividade do cartão em tempo real. Todos os webhooks do Portão 3 compartilham o mesmo envelope — veja [Receber webhooks](/guides/webhooks) para o modelo de entrega e como fazer deduplicação. ### Uma transação aconteceu em um cartão `CARD_TRANSACTION` (source `WALLET`) dispara quando um cartão é cobrado; uma autorização recusada dispara `CARD_TRANSACTION_REFUSED`. O `payload` espelha um item de transação: `cardId`, `billingAmount`, `balanceCategory` e o `cardTransaction` aninhado com os detalhes do estabelecimento e o `mcc`. ### Um cartão precisa de um código de verificação (tokenização) Quando um portador adiciona o cartão a uma carteira de dispositivo (Apple Pay, Google Pay), o emissor envia um código de ativação que você deve repassar ao portador: ```json theme={null} { "source": "WALLET", "event": "CARDLESS_PAYMENT_ACTIVATION_CODE_EVENT", "payload": { "walletId": "...", "cardId": "...", "activationCode": "976486", "deviceWalletName": "APPLE PAY" } } ``` Encaminhe `activationCode` ao portador para que ele possa concluir a validação do cartão em sua carteira de dispositivo. ## Próximos passos O envelope de notificação e o catálogo completo de eventos. Limites, regras e saldo disponível.