Manage and monitor cards

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:

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

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. Reference: GET .../wallets/{walletId}/cards · GET .../accounts/{accountId}/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.

# 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 · POST .../cards/{cardId}/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.

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

To list transactions across a whole wallet (cards, PIX, boleto, and transfers together), use the wallet transactions endpoint described in Wallets for your customers.

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

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

Getting Started

Integration guides

Cards

PIX & payments

Accounts & wallets

Building your integration

Manage and monitor cards

List cards

Block and unblock a card

Read a card’s transactions

Card webhooks

A transaction happened on a card

A card needs a verification code (tokenization)

Next steps

Receive webhooks

Control card spending

​List cards

​Block and unblock a card

​Read a card’s transactions

​Card webhooks

​A transaction happened on a card

​A card needs a verification code (tokenization)

​Next steps

Receive webhooks

Control card spending

List cards

Block and unblock a card

Read a card’s transactions

Card webhooks

A transaction happened on a card

A card needs a verification code (tokenization)

Next steps