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.

Uma cobrança foi estornada

CARD_TRANSACTION_REFUNDED (source WALLET) dispara quando o estabelecimento estorna uma cobrança, total ou parcialmente. O payload é a própria transação de estorno, no mesmo formato do payload de CARD_TRANSACTION — financialImpactType é CREDIT e billingAmount é o valor estornado, que pode ser menor que a cobrança original. Um estorno nunca dispara CARD_TRANSACTION, então quem assina só esse evento vê a cobrança, mas não o dinheiro voltando.

{
  "notificationId": "7f3c1a2e-5b8d-4e6f-9a0b-1c2d3e4f5a6b",
  "source": "WALLET",
  "event": "CARD_TRANSACTION_REFUNDED",
  "payload": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0d2",
    "realmId": "...",
    "organizationId": "...",
    "accountId": "...",
    "walletId": "...",
    "cardId": "...",
    "environment": "LIVE",
    "financialImpactType": "CREDIT",
    "billingAmount": 2500,
    "billingAmountAuthorized": 2500,
    "billingCurrency": "986",
    "balanceCategory": "FLEX_NATIONAL",
    "msgType": 1120,
    "txnType": 14,
    "responseCode": 400,
    "processingType": "INSTANT",
    "effectiveAt": "2026-01-15T14:02:11.000Z",
    "createdAt": "2026-01-15T14:02:40.000Z",
    "external": { "transactionId": "0F1E2D3C4B5A69788796A5B4C3D2E1F0" },
    "cardTransaction": {
      "merchantName": "LOJA EXEMPLO",
      "merchantId": "000000000000001",
      "merchantCity": "SAO PAULO",
      "merchantCountry": "BRA",
      "mcc": "5411",
      "posEntryMode": "E-Commerce",
      "txnAmount": 2500,
      "txnAmountAuthorized": 2500,
      "txnCurrency": "986",
      "localTime": "2026-01-15T14:02:11.000Z",
      "cleared": false,
      "reversed": false,
      "linkedTransactions": [
        {
          "transactionId": "66f1a2b3c4d5e6f7a8b9c0d1",
          "linkType": "CLEARING_CREDITS",
          "createdAt": "2026-01-15T14:02:11.000Z",
          "updatedAt": "2026-01-15T14:02:11.000Z"
        }
      ]
    }
  }
}

Campo	O que ler
`financialImpactType`	`CREDIT` — o dinheiro voltou para a carteira. Uma cobrança é `DEBIT`, uma autorização recusada é `NONE`.
`billingAmount`	O valor estornado, em centavos. Pode ser menor que a cobrança original (estorno parcial).
`cardTransaction.merchantName`, `merchantId`, `mcc`	O mesmo estabelecimento da cobrança original.
`cardTransaction.linkedTransactions[]`	O vínculo com a cobrança original: o item com `linkType: "CLEARING_CREDITS"` traz o `_id` da cobrança em `transactionId` — o mesmo `_id` recebido no webhook `CARD_TRANSACTION` dela. Use-o para casar o estorno com a cobrança do seu lado.

A transação da cobrança original recebe o vínculo espelhado, linkType: "CLEARING_CREDITED_BY", apontando para o estorno. Os outros tipos de vínculo (CLEARING_DEBITS / CLEARING_DEBITED_BY, a liquidação de uma cobrança) são etapas de processamento e podem ser ignorados ao casar estornos.

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, Samsung Pay), o emissor envia um código de ativação que você deve repassar ao portador:

{
  "notificationId": "...",
  "source": "WALLET",
  "event": "CARDLESS_PAYMENT_ACTIVATION_CODE_EVENT",
  "payload": {
    "realmId": "...",
    "organizationId": "...",
    "accountId": "...",
    "walletId": "...",
    "cardId": "...",
    "environment": "LIVE",
    "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. deviceWalletName é a carteira de dispositivo informada pelo emissor, e a grafia varia (Apple Pay, APPLE PAY). Os membros da carteira do cartão que usam o aplicativo móvel da Portão 3 também recebem o código por notificação push.

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

Uma cobrança foi estornada

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

​Uma cobrança foi estornada

​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

Uma cobrança foi estornada

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

Próximos passos