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?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": "Order 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"
      }
    }
  }'

Field	Notes
`txnCurrency`	Always `986` (BRL).
`txnAmount`	Centavos.
`txnCanAmountChange`	`false` to lock the amount; `true` to let the payer change it.
`dueDate`	`YYYY-MM-DD`, today or later. Leave it out for a static QR Code — see below.
`expiresAt`	`YYYY-MM-DD`, on or after `dueDate`: the last day the charge can be paid. Defaults to `dueDate`.
`txnFineAmount`, `txnInterestAmount`, `txnDiscountAmount`, `txnRebateAmount`	Optional, only with `dueDate`: a fine and interest for paying late, a discount for paying early, a rebate.
`description`	Shown to the payer.
`customer`	The payer’s `name` (up to 50 characters), `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. `postalCode` keeps its dash (`38411-122`).

What you send decides the kind of charge:

No dueDate — a static QR Code for txnAmount. It never expires and can’t be canceled. Only the payer’s name is used — up to 25 characters — and description is up to 39.
dueDate with no fine, interest, discount or rebate — payable until the end of expiresAt (or dueDate), in UTC.
dueDate with a fine, interest, discount or rebate — paid before dueDate it gets the discount, after it the fine and the interest; payable until expiresAt. The payer’s bank works out the amount due on the day.

The response is the charge, with status: "ACTIVE", the emv string and its _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"
}

Render emv as a QR Code, or offer it as Copia e Cola text for the payer to paste into their bank app. key is the wallet’s Pix key the charge pays into — the wallet needs an active one (see Pix keys). Reference: Create a Pix charge

Keep ?forceWallet=true in the URL so the payment is credited to the wallet in the path. Without it, the QR Code is issued for your organization’s main wallet: the payment is credited there, and a charge that belongs to another wallet is never marked PAID. 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, the charge moves to PAID, with the amount received in confirmedAmount, and 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:

Get one charge — GET .../wallets/{walletId}/pix-billing/{pixId}
List a wallet’s charges, newest first, paginated with limit and next: GET .../wallets/{walletId}/pix-billing. The account, organization and realm have lists too.
Show a payment page — GET /pix-billing/{pixBillingId} needs no token: anyone with the charge’s ID can read it, so it returns only what the payer needs — the status, amount, dates, description, emv and Pix key, and the payer’s name and masked document. Use it only for a page you show the payer, and send x-environment: LIVE.

Cancel a charge

A charge with a dueDate that is still ACTIVE can be canceled: its QR Code can no longer be paid and it moves to CANCELED. A static QR Code (no dueDate) and a PAID charge can’t be. See Cancel a Pix charge.

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

Cancel 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

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

Cancel a charge

Next steps