Gerenciar e monitorar cartões

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:

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'

Ou liste todos os cartões de uma conta (todas as carteiras):

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'

Ambos retornam { "items": [...], "next": "<cursor>" }. 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. Referência: GET .../wallets/{walletId}/cards · GET .../accounts/{accountId}/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.

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

Referência: POST .../cards/{cardId}/block · POST .../cards/{cardId}/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.

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'

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

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.

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

{
  "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.

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

Gerenciar e monitorar cartões

Listar cartões

Bloquear e desbloquear um cartão

Ler as transações de um cartão

Webhooks de cartão

Uma transação aconteceu em um cartão

Um cartão precisa de um código de verificação (tokenização)

Próximos passos

Receber webhooks

Controlar gastos do cartão

​Listar cartões

​Bloquear e desbloquear um cartão

​Ler as transações de um cartão

​Webhooks de cartão

​Uma transação aconteceu em um cartão

​Um cartão precisa de um código de verificação (tokenização)

​Próximos passos

Receber webhooks

Controlar gastos do cartão

Listar cartões

Bloquear e desbloquear um cartão

Ler as transações de um cartão

Webhooks de cartão

Uma transação aconteceu em um cartão

Um cartão precisa de um código de verificação (tokenização)

Próximos passos