Emitir cartões virtuais

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

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

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

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.

Referência: POST .../wallets/{walletId}/cards

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.

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:

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

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.

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

Próximos passos

Controlar gastos do cartão

Adicione limites e regras de categoria de estabelecimento, e consulte o saldo disponível.

Gerenciar e monitorar cartões

Bloqueie, desbloqueie e leia o histórico de transações de um cartão.

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

Emitir cartões virtuais

Fluxo

Passo 1: Crie o cartão

Passo 2: Leia os detalhes do cartão

Diretrizes para o nome do portador

Reutilizando um cartão para cobranças futuras

Próximos passos

Controlar gastos do cartão

Gerenciar e monitorar cartões

​Fluxo

​Passo 1: Crie o cartão

​Passo 2: Leia os detalhes do cartão

​Diretrizes para o nome do portador

​Reutilizando um cartão para cobranças futuras

​Próximos passos

Controlar gastos do cartão

Gerenciar e monitorar cartões

Fluxo

Passo 1: Crie o cartão

Passo 2: Leia os detalhes do cartão

Diretrizes para o nome do portador

Reutilizando um cartão para cobranças futuras

Próximos passos