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 charge was refunded

CARD_TRANSACTION_REFUNDED (source WALLET) fires when the merchant refunds a charge, fully or partially. The payload is the refund transaction itself, in the same shape as a CARD_TRANSACTION payload — financialImpactType is CREDIT and billingAmount is the refunded amount, which can be less than the original charge. A refund never fires CARD_TRANSACTION, so a subscriber to that event alone sees the charge but not the money coming back.

{
  "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"
        }
      ]
    }
  }
}

Field	What to read
`financialImpactType`	`CREDIT` — money came back into the wallet. A charge is `DEBIT`, a refused authorization `NONE`.
`billingAmount`	The refunded amount, in cents. It can be less than the original charge (a partial refund).
`cardTransaction.merchantName`, `merchantId`, `mcc`	The same merchant as the original charge.
`cardTransaction.linkedTransactions[]`	The link to the original charge: the item with `linkType: "CLEARING_CREDITS"` carries the charge’s `_id` in `transactionId` — the same `_id` you received in its `CARD_TRANSACTION` webhook. Use it to match the refund to the charge on your side.

The original charge’s own transaction gains the mirror link, linkType: "CLEARING_CREDITED_BY", pointing at the refund. Other link types (CLEARING_DEBITS / CLEARING_DEBITED_BY, the settlement of a charge) are processing steps and can be ignored when matching refunds.

A card needs a verification code (tokenization)

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

{
  "notificationId": "...",
  "source": "WALLET",
  "event": "CARDLESS_PAYMENT_ACTIVATION_CODE_EVENT",
  "payload": {
    "realmId": "...",
    "organizationId": "...",
    "accountId": "...",
    "walletId": "...",
    "cardId": "...",
    "environment": "LIVE",
    "activationCode": "976486",
    "deviceWalletName": "APPLE PAY"
  }
}

Forward activationCode to the cardholder so they can finish validating the card in their device wallet. deviceWalletName is the device wallet as reported by the issuer, and its casing varies (Apple Pay, APPLE PAY). Members of the card’s wallet who use the Portão 3 mobile app also receive the code as a push notification.

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 charge was refunded

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 charge was refunded

​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 charge was refunded

A card needs a verification code (tokenization)

Next steps