> ## Documentation Index
> Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Issue virtual cards

> Create a virtual card, read its PAN and CVV, and use it for a charge

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

```mermaid theme={null}
sequenceDiagram
  participant You
  participant P3 as Portão 3
  participant Merchant
  You->>P3: POST /cards
  P3->>You: cardId
  You->>P3: GET /cards/{cardId}/details
  P3->>You: PAN, CVV, expiry
  You->>Merchant: Send card details for the charge
```

## 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).

```bash theme={null}
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](/guides/card-spending-controls)).                                        |
| `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. |

<Tip>
  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](/guides/card-spending-controls).
</Tip>

Reference: [`POST .../wallets/{walletId}/cards`](/api-reference/banking/cards/realms-organizations-accounts-wallets-cards-1)

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

```bash theme={null}
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:

```json theme={null}
{
  "_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`](/api-reference/banking/cards/realms-organizations-accounts-wallets-cards-details)

<Warning>
  `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.
</Warning>

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

```mermaid theme={null}
sequenceDiagram
  participant You
  participant P3 as Portão 3
  participant Merchant
  You->>P3: POST /card-limit (new amount + window)
  P3->>You: 201 Created
  You->>Merchant: Send the same card for the next charge
```

The request body and the difference between a card limit and a card rule are covered in [Control card spending](/guides/card-spending-controls).

## Next steps

<CardGroup cols={2}>
  <Card title="Control card spending" icon="sliders" href="/guides/card-spending-controls">
    Add limits and merchant-category rules, and check available balance.
  </Card>

  <Card title="Manage and monitor cards" icon="list" href="/guides/manage-cards">
    Block, unblock, and read the transaction history for a card.
  </Card>
</CardGroup>