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

# Emitir cartões virtuais

> Crie um cartão virtual, leia seu PAN e CVV, e use-o para uma cobrança

Este é o fluxo de Banking mais comum. Você cria um cartão virtual dentro de uma carteira, lê seu número completo e CVV, e entrega esses dados a um estabelecimento (uma companhia aérea, um hotel, uma plataforma de anúncios) para ser cobrado. O mesmo fluxo atende tanto casos de uso de cobrança única (uma passagem, uma reserva) quanto cartões reutilizáveis (uma conta de anúncios contínua).

## Fluxo

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

## Passo 1: Crie o cartão

Crie o cartão na carteira de destino. O cartão é criado como `ACTIVE` e retorna seu `_id` (o `cardId` que você usa em todos os outros lugares).

```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"]
      }
    ]
  }'
```

| Campo          | Notas                                                                                                                                                                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`         | `VIRTUAL`.                                                                                                                                                                                                                                   |
| `singleUse`    | `true` bloqueia o cartão após sua primeira transação liquidada. Use `false` para cartões reutilizáveis e adicione limites por cobrança (veja [Controlar gastos do cartão](/guides/card-spending-controls)).                                  |
| `customFields` | Objeto de formato livre para correlacionar o cartão com seus próprios registros (uma reserva, um cliente). Retornado no cartão e em suas transações.                                                                                         |
| `cardLimits`   | Limite de gasto opcional criado junto com o cartão. `amount` é em centavos; `startDate`/`endDate` delimitam a janela de validade — use a data de hoje para uma cobrança no mesmo dia; `ruleIds` são as regras de gasto que o limite permite. |

<Tip>
  Você pode criar o cartão sem `cardLimits` e anexar um limite depois — útil para cartões reutilizáveis que recebem um novo limite antes de cada cobrança. Veja [Controlar gastos do cartão](/guides/card-spending-controls).
</Tip>

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

## Passo 2: Leia os detalhes do cartão

A resposta de criação retorna apenas o PAN mascarado. Para obter o número completo e o CVV necessários para uma cobrança, chame o endpoint de detalhes com o `cardId` do passo 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'
```

A resposta adiciona os campos sensíveis ao objeto do cartão:

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

Use `pan`, `cvv` e `expiryDate` para completar a cobrança com o estabelecimento.

Referência: [`GET .../cards/{cardId}/details`](/api-reference/banking/cards/realms-organizations-accounts-wallets-cards-details)

<Warning>
  `pan` e `cvv` são credenciais completas do cartão. Nunca faça log delas nem as armazene em texto puro — leia, encaminhe ao estabelecimento e descarte.
</Warning>

### Diretrizes para o nome do portador

Quando um estabelecimento exigir um nome de portador, siga estas regras para que a cobrança não seja rejeitada:

* Use pelo menos dois nomes, idealmente três, separados por um espaço — `MARCOS DANTAS` ou `MARCOS O DANTAS`, não `MARCOS`.
* Sempre em maiúsculas.
* Sem dígitos ou caracteres especiais.

## Reutilizando um cartão para cobranças futuras

Para um cartão reutilizável (`singleUse: false`), não crie um novo cartão por cobrança. Em vez disso, mantenha o cartão e adicione um novo limite antes de cada nova transação:

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

O corpo da requisição e a diferença entre um limite de cartão e uma regra de cartão são explicados em [Controlar gastos do cartão](/guides/card-spending-controls).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Controlar gastos do cartão" icon="sliders" href="/guides/card-spending-controls">
    Adicione limites e regras de categoria de estabelecimento, e consulte o saldo disponível.
  </Card>

  <Card title="Gerenciar e monitorar cartões" icon="list" href="/guides/manage-cards">
    Bloqueie, desbloqueie e leia o histórico de transações de um cartão.
  </Card>
</CardGroup>