Carteiras para seus clientes

Uma carteira é a conta que guarda saldos, cartões e chaves PIX. Muitas integrações abrem uma carteira por cliente final para que o dinheiro, os cartões e as cobranças de cada cliente fiquem isolados. Este guia cobre como criar uma carteira, registrar uma chave PIX nela, ler seus saldos, movimentar dinheiro entre carteiras e ler suas transações.

Criar uma carteira

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{ "currency": "986", "name": "Cliente 4471" }'

currency é sempre 986 (real) e name é obrigatório. A carteira é compartilhada com os usuários em shared; se você omitir o campo, você se torna o único OWNER. Ela é criada com status: "PENDING" e retorna seu _id (o walletId). Ela passa a ACTIVE assim que provisionada, geralmente em segundos — só então pode ter saldo e movimentar dinheiro.

{
  "_id": "6981f701fac3b778cf808272",
  "name": "Cliente 4471",
  "type": "SHARED",
  "currency": "986",
  "status": "PENDING",
  "role": "CHECKING"
}

Referência: Create a wallet

Ler uma carteira e seus saldos

Busque uma carteira para ler seus saldos. O saldo é dividido em categorias; totalBalance é a soma.

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

{
  "_id": "65425d6b3922c7d5aee353c5",
  "status": "ACTIVE",
  "totalBalance": 1378,
  "balances": [
    { "category": "FLEX_INTERNATIONAL", "amount": 1378 },
    { "category": "FLEX_NATIONAL", "amount": 0 },
    { "category": "BLOCKED", "amount": 0 }
  ]
}

Os valores estão em centavos. FLEX_INTERNATIONAL é a categoria de uso geral utilizada na maioria dos fluxos. Envie includeBalances=false quando precisar só da carteira, e use default como walletId para ler a carteira principal da organização. Referência: Get a wallet

Registrar uma chave PIX

Uma carteira precisa de uma chave PIX (DICT) para receber cobranças. Crie uma chave aleatória (EVP) na carteira — não envie value, o banco gera a chave:

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix-dict' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "EVP" }'

A resposta (201) retorna o _id da chave, o value e o status: "ACTIVE". Use esse valor como o pixDict ao criar cobranças ou autorizações de PIX Automático. Gerencie as chaves com:

Listar chaves — List a wallet’s Pix keys (?status=ACTIVE para as chaves em uso)
Remover uma chave — Remove a Pix key (retorna 204)

Gerenciar chaves Pix cobre todos os tipos de chave, a confirmação de uma chave com código e as respostas às reivindicações que outras instituições abrem para as suas chaves.

Pedir dinheiro à carteira principal da organização (solicitações de transferência)

Uma solicitação de transferência movimenta dinheiro entre uma carteira e a carteira principal da organização quando é confirmada — depois de aprovada, quando as políticas de negócio da organização exigem. Um amount positivo pede dinheiro à carteira principal; um negativo devolve.

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transfer-requests' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{ "destinationCategory": "FLEX_INTERNATIONAL", "amount": 250000, "description": "Verba de eventos" }'

O policy.actions.autoAction da resposta diz o próximo passo: APPROVE — confirme e o dinheiro é movimentado; NONE — envie para aprovação, e ela é confirmada quando aprovada; DENY — as políticas a recusam. Admins da organização — clientes de API inclusive — podem confirmar uma solicitação ainda REQUESTED seja qual for a decisão das políticas. Se as políticas não puderem ser avaliadas no momento, policy vem como { "error": "POLICY_EVALUATION_UNAVAILABLE" }: a solicitação continua salva, e confirmá-la ou enviá-la para aprovação avalia as políticas de novo. Antes de confirmá-la ou enviá-la para aprovação, você pode atualizar a solicitação para preencher campos personalizados ou mudar o dia dela; o valor e a categoria são fixos — para mudá-los, cancele a solicitação e crie outra. Políticas de negócio e aprovações explica o fluxo completo: como uma política decide, quando confirmar e quando enviar para aprovação, e o que acontece depois que os aprovadores decidem. Referência: Create a transfer request

Ler transações

Liste todas as transações de uma carteira — cartões, PIX, boleto, tarifas e P2P juntos. Filtre por tipo e intervalo de datas; pagine com o cursor next.

curl 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions?transactionType=PIX&startDate=2026-01-01&endDate=2026-01-31' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

transactionType aceita CARD, PIX, BOLETO, FEE ou P2P. O formato de cada item depende do seu tipo (um bloco cardTransaction ou pixTransaction é aninhado conforme o caso). Referência: List a wallet’s transactions

Para o histórico somente de cartão, use o endpoint de transações por cartão descrito em Gerenciar e monitorar cartões.

Cada carteira também tem limites de PIX, TED e boleto por período — veja Get transaction limits.

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

Carteiras para seus clientes

Criar uma carteira

Ler uma carteira e seus saldos

Registrar uma chave PIX

Pedir dinheiro à carteira principal da organização (solicitações de transferência)

Ler transações

Próximos passos

Cobrar com PIX

Emitir cartões virtuais

​Criar uma carteira

​Ler uma carteira e seus saldos

​Registrar uma chave PIX

​Pedir dinheiro à carteira principal da organização (solicitações de transferência)

​Ler transações

​Próximos passos

Cobrar com PIX

Emitir cartões virtuais

Criar uma carteira

Ler uma carteira e seus saldos

Registrar uma chave PIX

Pedir dinheiro à carteira principal da organização (solicitações de transferência)

Ler transações

Próximos passos