Charge with PIX

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

Step 1: Create the charge

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:

{
  "_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

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.

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

{
  "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 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
Fetch one charge by ID — a lightweight lookup when you only have the charge ID: GET /pix-billing/{pixBillingId}. Like every Banking endpoint, it requires your bearer token.

Getting Started

Integration guides

Cards

PIX & payments

Accounts & wallets

Building your integration

Flow

Step 1: Create the charge

Step 2: Get notified when it’s paid

Look up a charge

Next steps

Recurring billing with Pix Automático

Receive webhooks

​Flow

​Step 1: Create the charge

​Step 2: Get notified when it’s paid

​Look up a charge

​Next steps

Recurring billing with Pix Automático

Receive webhooks

Flow

Step 1: Create the charge

Step 2: Get notified when it’s paid

Look up a charge

Next steps