Issue virtual cards

This is the most common Banking flow. You create a virtual card inside a wallet, read its full number and CVV, and hand those details to a merchant (an airline, a hotel, an ad platform) to be charged. The same flow backs single-charge use cases (one ticket, one booking) and reusable cards (an ongoing ad account).

Flow

Step 1: Create the card

Create the card in the target wallet. The card is created ACTIVE and returns its _id (the cardId you use everywhere else).

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "VIRTUAL",
    "singleUse": false,
    "customFields": { "reservationId": "1234" },
    "cardLimits": [
      {
        "name": "Rule",
        "amount": 10000,
        "startDate": "2026-07-01",
        "endDate": "2026-07-01",
        "ruleIds": ["FLEX_INTERNATIONAL"]
      }
    ]
  }'

Field	Notes
`type`	`VIRTUAL`.
`singleUse`	`true` blocks the card after its first cleared transaction. Use `false` for reusable cards and add limits per charge (see Control card spending).
`customFields`	Free-form object to correlate the card with your own records (a booking, a reservation, a customer). Echoed back on the card and its transactions.
`cardLimits`	Optional spend limit created together with the card. `amount` is in centavos; `startDate`/`endDate` bound the validity window — use today’s date for a same-day charge; `ruleIds` are the spending rules the limit allows.

You can create the card without cardLimits and attach a limit later — useful for reusable cards that get a fresh limit before each charge. See Control card spending.

Reference: POST .../wallets/{walletId}/cards

Step 2: Read the card details

The create response only returns the masked PAN. To get the full number and CVV needed for a charge, call the details endpoint with the cardId from step 1.

curl 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}/details' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

The response adds the sensitive fields to the card object:

{
  "_id": "691cb583e72453367c11da38",
  "panMasked": "524674******3744",
  "expiryDate": "11/2031",
  "status": "ACTIVE",
  "pan": "5246743189283744",
  "cvv": "999"
}

Use pan, cvv, and expiryDate to complete the charge with the merchant. Reference: GET .../cards/{cardId}/details

pan and cvv are full card credentials. Never log them or store them in plaintext — read them, forward them to the merchant, and discard them.

Cardholder name guidelines

When a merchant requires a cardholder name, follow these rules so the charge isn’t rejected:

Use at least two names, ideally three, separated by a space — MARCOS DANTAS or MARCOS O DANTAS, not MARCOS.
Always uppercase.
No digits or special characters.

Reusing a card for future charges

For a reusable card (singleUse: false), don’t create a new card per charge. Instead, keep the card and add a fresh limit before each new transaction: The request body and the difference between a card limit and a card rule are covered in Control card spending.

Getting Started

Integration guides

Cards

PIX & payments

Accounts & wallets

Building your integration

Issue virtual cards

Flow

Step 1: Create the card

Step 2: Read the card details

Cardholder name guidelines

Reusing a card for future charges

Next steps

Control card spending

Manage and monitor cards

​Flow

​Step 1: Create the card

​Step 2: Read the card details

​Cardholder name guidelines

​Reusing a card for future charges

​Next steps

Control card spending

Manage and monitor cards

Flow

Step 1: Create the card

Step 2: Read the card details

Cardholder name guidelines

Reusing a card for future charges

Next steps