> ## 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.

# Charge with PIX

> Generate a PIX QR Code (Copia e Cola) and get notified when it's paid

To receive money, create a **PIX charge** (`pix-billing`). Portão 3 returns an EMV string — the Copia e Cola / QR Code payload — that you display to the payer. When they pay, you get a `PIX_BILLING_PAID` webhook.

## Flow

```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
```

## Step 1: Create the charge

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

| Field                | Notes                                                                                                                                                                                                                                                                        |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `txnCurrency`        | `986` (BRL).                                                                                                                                                                                                                                                                 |
| `txnAmount`          | Centavos.                                                                                                                                                                                                                                                                    |
| `txnCanAmountChange` | `false` to lock the amount; `true` to let the payer choose.                                                                                                                                                                                                                  |
| `description`        | Shown to the payer.                                                                                                                                                                                                                                                          |
| `customer`           | The payer's name, `document`, email, and address. `document` is a CPF (11 digits) or a CNPJ (14 characters, unformatted, uppercased) — per Receita Federal NT 49/2024, CNPJs may include letters `A–Z` in the first 12 positions, with only the last 2 check digits numeric. |

The response includes the `emv` string and the charge `_id`:

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

Render `emv` as a QR Code, or offer it as Copia e Cola text for the payer to paste into their bank app.

Reference: [`POST .../wallets/{walletId}/pix-billing`](/api-reference/banking/pix-charges/realms-organizations-accounts-wallets-pix-billing-1)

<Tip>
  Add `?forceWallet=true` to the URL to credit the **specific wallet** in the path. Without it, payments are routed to your organization's default wallet. This matters when you keep a wallet per end customer — see [Wallets for your customers](/guides/wallets).
</Tip>

## Step 2: Get notified when it's paid

When the payer completes the PIX, Portão 3 sends a `PIX_BILLING_PAID` webhook. The `payload` is the charge with `status: "PAID"`:

```json theme={null}
{
  "source": "WALLET",
  "event": "PIX_BILLING_PAID",
  "payload": {
    "_id": "68823710b8a3dbd2b90ff8d5",
    "status": "PAID",
    "txnAmount": 28500
  }
}
```

Match the `payload._id` to the charge you created in step 1. See [Receive webhooks](/guides/webhooks) for the delivery envelope.

## Look up a charge

Poll a charge's status, or list charges, instead of (or alongside) webhooks:

* **List charges** — paginated with `limit` and `next`: [`GET .../wallets/{walletId}/pix-billing`](/api-reference/banking/pix-charges/realms-organizations-accounts-wallets-pix-billing)
* **Fetch one charge by ID** — a lightweight lookup when you only have the charge ID: [`GET /pix-billing/{pixBillingId}`](/api-reference/banking/pix-charges/pix-billing). Like every Banking endpoint, it requires your bearer token.

## Next steps

<CardGroup cols={2}>
  <Card title="Recurring billing with Pix Automático" icon="repeat" href="/guides/pix-automatico">
    Authorize a recurring debit instead of a one-off charge.
  </Card>

  <Card title="Receive webhooks" icon="bell" href="/guides/webhooks">
    The notification envelope and event catalog.
  </Card>
</CardGroup>