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

A carteira é criada com status: "PENDING" e retorna seu _id (o walletId). Ela passa a ACTIVE assim que provisionada.

{
  "_id": "6981f701fac3b778cf808272",
  "currency": "986",
  "status": "PENDING",
  "role": "CHECKING"
}

Referência: POST .../accounts/{accountId}/wallets

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. Referência: GET .../wallets/{walletId}

Registrar uma chave PIX

Uma carteira precisa de uma chave PIX (DICT) para receber cobranças. Crie uma chave aleatória (EVP) na carteira:

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 retorna o value da chave e seu 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 — GET .../wallets/{walletId}/pix-dict
Remover uma chave — POST .../pix-dict/{pixDictId}/remove (retorna 204)

Movimentar dinheiro entre carteiras (P2P)

Transfira um saldo de uma carteira para outra — por exemplo, varrendo a carteira de um cliente para a carteira da sua organização. A transferência é interna e liquida instantaneamente.

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transfers-p2p' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceCategory": "FLEX_INTERNATIONAL",
    "destinationRealmId": "...",
    "destinationOrganizationId": "...",
    "destinationAccountId": "...",
    "destinationWalletId": "...",
    "destinationCategory": "FLEX_INTERNATIONAL",
    "amount": 316
  }'

Campo	Observações
`sourceCategory` / `destinationCategory`	Categoria de saldo a debitar e creditar.
`destination*`	O endereço completo da carteira receptora (realm, organização, conta, carteira).
`amount`	Centavos.

A resposta retorna status: "PROCESSED" e as carteiras de origem e destino atualizadas com seus novos saldos. Referência: POST .../wallets/{walletId}/transfers-p2p

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: GET .../wallets/{walletId}/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.

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

Movimentar dinheiro entre carteiras (P2P)

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

​Movimentar dinheiro entre carteiras (P2P)

​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

Movimentar dinheiro entre carteiras (P2P)

Ler transações

Próximos passos