Cobrar com PIX

Para receber dinheiro, crie uma cobrança PIX (pix-billing). O Portão 3 retorna uma string EMV — o payload do Copia e Cola / QR Code — que você exibe ao pagador. Quando ele pagar, você recebe um webhook PIX_BILLING_PAID.

Fluxo

Etapa 1: Criar a cobrança

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix-billing' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "txnCurrency": "986",
    "txnAmount": 28500,
    "txnCanAmountChange": false,
    "description": "Order 4821",
    "customer": {
      "name": "CERVEJARIA GOOD BEER",
      "document": "12345678000190",
      "email": "user@email.com",
      "address": {
        "street": "Avenida Francisco Galassi",
        "number": "950",
        "neighborhood": "Morada da Colina",
        "postalCode": "38411-122",
        "city": "UBERLANDIA",
        "state": "MG"
      }
    }
  }'

Campo	Observações
`txnCurrency`	`986` (BRL).
`txnAmount`	Centavos.
`txnCanAmountChange`	`false` para travar o valor; `true` para deixar o pagador escolher.
`description`	Exibida ao pagador.
`customer`	Nome do pagador, `document`, e-mail e endereço. `document` é um CPF (11 dígitos) ou um CNPJ (14 caracteres, sem formatação, em maiúsculas) — conforme a NT 49/2024 da Receita Federal, o CNPJ pode conter letras `A–Z` nas 12 primeiras posições, e apenas os 2 dígitos verificadores finais permanecem numéricos.

A resposta inclui a string emv e o _id da cobrança:

{
  "_id": "68823710b8a3dbd2b90ff8d5",
  "status": "ACTIVE",
  "txnAmount": 28500,
  "emv": "00020126700014br.gov.bcb.pix...6304ABCD",
  "key": "589bbd4b-62d1-45b3-8a29-77b84b7ba3b6"
}

Renderize o emv como um QR Code, ou disponibilize-o como texto Copia e Cola para o pagador colar no aplicativo do banco. Referência: POST .../wallets/{walletId}/pix-billing

Adicione ?forceWallet=true à URL para creditar a carteira específica informada no path. Sem isso, os pagamentos são roteados para a carteira padrão da sua organização. Isso é importante quando você mantém uma carteira por cliente final — veja Carteiras para seus clientes.

Etapa 2: Ser notificado quando for pago

Quando o pagador finaliza o PIX, o Portão 3 envia um webhook PIX_BILLING_PAID. O payload é a cobrança com status: "PAID":

{
  "source": "WALLET",
  "event": "PIX_BILLING_PAID",
  "payload": {
    "_id": "68823710b8a3dbd2b90ff8d5",
    "status": "PAID",
    "txnAmount": 28500
  }
}

Faça a correspondência do payload._id com a cobrança que você criou na etapa 1. Veja Receber webhooks para o envelope de entrega.

Consultar uma cobrança

Consulte o status de uma cobrança, ou liste cobranças, em vez de (ou junto com) webhooks:

Listar cobranças — paginado com limit e next: GET .../wallets/{walletId}/pix-billing
Buscar uma cobrança por ID — uma consulta leve quando você tem apenas o ID da cobrança: GET /pix-billing/{pixBillingId}. Como todo endpoint de Banking, requer seu bearer token.

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

Fluxo

Etapa 1: Criar a cobrança

Etapa 2: Ser notificado quando for pago

Consultar uma cobrança

Próximos passos

Cobrança recorrente com PIX Automático

Receber webhooks

​Fluxo

​Etapa 1: Criar a cobrança

​Etapa 2: Ser notificado quando for pago

​Consultar uma cobrança

​Próximos passos

Cobrança recorrente com PIX Automático

Receber webhooks

Fluxo

Etapa 1: Criar a cobrança

Etapa 2: Ser notificado quando for pago

Consultar uma cobrança

Próximos passos