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?forceWallet=true' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "txnCurrency": "986",
    "txnAmount": 28500,
    "txnCanAmountChange": false,
    "dueDate": "2026-11-20",
    "expiresAt": "2026-12-20",
    "description": "Pedido 4821",
    "customer": {
      "name": "CERVEJARIA GOOD BEER",
      "document": "12345678000195",
      "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`	Sempre `986` (BRL).
`txnAmount`	Centavos.
`txnCanAmountChange`	`false` para travar o valor; `true` para deixar o pagador alterá-lo.
`dueDate`	`AAAA-MM-DD`, hoje ou depois. Omita para um QR Code estático — veja abaixo.
`expiresAt`	`AAAA-MM-DD`, igual ou posterior ao `dueDate`: o último dia em que a cobrança pode ser paga. Padrão: o `dueDate`.
`txnFineAmount`, `txnInterestAmount`, `txnDiscountAmount`, `txnRebateAmount`	Opcionais, só com `dueDate`: multa e juros por atraso, desconto por antecipação, abatimento.
`description`	Exibida ao pagador.
`customer`	`name` do pagador (até 50 caracteres), `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. O `postalCode` mantém o hífen (`38411-122`).

O que você envia define o tipo de cobrança:

Sem dueDate — um QR Code estático de txnAmount. Ele nunca expira e não pode ser cancelado. Só o name do pagador é usado — até 25 caracteres — e a description tem até 39.
Com dueDate, sem multa, juros, desconto ou abatimento — pagável até o fim do dia do expiresAt (ou do dueDate), em UTC.
Com dueDate e multa, juros, desconto ou abatimento — paga antes do dueDate, tem o desconto; depois, a multa e os juros; pagável até o expiresAt. O banco do pagador calcula o valor devido no dia.

A resposta é a cobrança, com status: "ACTIVE", a string emv e o seu _id:

{
  "_id": "68823710b8a3dbd2b90ff8d5",
  "status": "ACTIVE",
  "txnAmount": 28500,
  "dueDate": "2026-11-20T00:00:00.000Z",
  "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. A key é a chave Pix da carteira para a qual a cobrança paga — a carteira precisa de uma chave ativa (veja Chaves Pix). Referência: Create a Pix charge

Mantenha ?forceWallet=true na URL para que o pagamento seja creditado na carteira do path. Sem isso, o QR Code é emitido para a carteira principal da sua organização: o pagamento é creditado nela, e uma cobrança que pertence a outra carteira nunca é marcada como PAID. 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, a cobrança passa para PAID, com o valor recebido em confirmedAmount, e 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:

Buscar uma cobrança — GET .../wallets/{walletId}/pix-billing/{pixId}
Listar as cobranças de uma carteira, das mais recentes para as mais antigas, paginado com limit e next: GET .../wallets/{walletId}/pix-billing. A conta, a organização e o realm também têm listas.
Exibir uma página de pagamento — GET /pix-billing/{pixBillingId} não exige token: qualquer pessoa com o ID da cobrança consegue lê-la, por isso ela devolve só o que o pagador precisa — o status, o valor, as datas, a descrição, o emv e a chave Pix, e o nome e o documento mascarado do pagador. Use-o só numa página que você exibe ao pagador, e envie x-environment: LIVE.

Cancelar uma cobrança

Uma cobrança com dueDate que ainda está ACTIVE pode ser cancelada: o QR Code deixa de poder ser pago e ela passa para CANCELED. Um QR Code estático (sem dueDate) e uma cobrança PAID não podem. Veja Cancel a Pix charge.

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

Cancelar 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

​Cancelar 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

Cancelar uma cobrança

Próximos passos