> ## Documentation Index
> Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Cobrar com PIX

> Gere um QR Code PIX (Copia e Cola) e seja notificado quando for pago

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

```mermaid theme={null}
sequenceDiagram
  participant You
  participant P3 as Portão 3
  participant Payer
  participant Bank
  You->>P3: POST /pix-billing
  P3->>You: 200 with emv (Copia e Cola)
  You->>Payer: Show QR Code / Copia e Cola
  Payer->>Bank: Pay
  Bank->>P3: Payment received
  P3->>You: Webhook PIX_BILLING_PAID
```

## Etapa 1: Criar a cobrança

```bash theme={null}
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:

```json theme={null}
{
  "_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`](/api-reference/banking/pix-charges/realms-organizations-accounts-wallets-pix-billing-1)

<Tip>
  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](/guides/wallets).
</Tip>

## 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"`:

```json theme={null}
{
  "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](/guides/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`](/api-reference/banking/pix-charges/realms-organizations-accounts-wallets-pix-billing)
* **Buscar uma cobrança por ID** — uma consulta leve quando você tem apenas o ID da cobrança: [`GET /pix-billing/{pixBillingId}`](/api-reference/banking/pix-charges/pix-billing). Como todo endpoint de Banking, requer seu bearer token.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Cobrança recorrente com PIX Automático" icon="repeat" href="/guides/pix-automatico">
    Autorize um débito recorrente em vez de uma cobrança avulsa.
  </Card>

  <Card title="Receber webhooks" icon="bell" href="/guides/webhooks">
    O envelope de notificação e o catálogo de eventos.
  </Card>
</CardGroup>