Send a Pix payment

Sending a Pix is a flow of separate steps. You create the payment, which resolves who you’re paying and the amount; you set its details if any are missing; then you confirm it, and only then the money moves. If your organization’s business policies require approval for the payment, you send it for approval instead of confirming it — see Business policies and approvals.

Flow

Step 1: Create the payment

Identify the recipient by a Pix key, a Pix Copia e Cola / QR code, or the recipient’s bank details.

By Pix key
By QR code
By bank details

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiationType": "DICT",
    "dict": "CNPJ",
    "key": "12345678000195",
    "amount": 123000,
    "category": "FLEX_INTERNATIONAL",
    "description": "Order 4821"
  }'

Field	Notes
`initiationType`	`DICT` for a key.
`dict`	Key type: `PHONE`, `EMAIL`, `CPF`, `CNPJ`, or `EVP` (random).
`key`	The key. Phone as `+55XXXXXXXXXXX`; e-mail in lowercase; CPF as 11 digits; CNPJ as 14 characters, unformatted and uppercased — per Receita Federal NT 49/2024, CNPJs may include letters `A–Z` in the first 12 positions (only the last 2 check digits stay numeric).
`amount`	In centavos. Required.
`category`	The wallet balance category to charge. With it, you can confirm right after creating.
`description`	Goes to the recipient with the payment.

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiationType": "COPY_PASTE",
    "emv": "00020101021226870014br.gov.bcb.pix2565...6304ABCD"
  }'

Pass the Pix Copia e Cola code, or the code read from the QR code, in emv — with COPY_PASTE, or DYNAMIC_QRCODE / STATIC_QRCODE / UNDEFINED_QRCODE when you read a QR code. The amount comes from the QR code itself: read it in txnUpdatedAmount. When the QR code lets the payer choose the amount (txnAllowAmountChange: true), it is 0 and you set it in step 2.

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiationType": "FULL_BANK_DETAILS",
    "credit_party": {
      "name": "Gráfica Aurora Ltda",
      "document": "12345678000195",
      "bank_ispb": "60746948",
      "branch": "0001",
      "accountNumber": "123456",
      "accountType": "CACC"
    },
    "amount": 123000,
    "category": "FLEX_INTERNATIONAL"
  }'

accountType is CACC (checking), SLRY (salary), SVGS (savings) or TRAN (payment account).

The payment is created as REQUESTED — nothing is paid yet. Review who you’re paying (creditParty) and how much (txnUpdatedAmount) before going on:

{
  "_id": "6726a4f1b4d3e80012c9a3f1",
  "status": "REQUESTED",
  "initiationType": "DICT",
  "txnUpdatedAmount": 123000,
  "creditParty": { "name": "Gráfica Aurora Ltda", "document": "12345678000195", "bankIspb": "60746948", "key": "12345678000195", "keyType": "CNPJ" },
  "receipt": { "endToEndId": "E12345678202611021312k7Q2mX9pL4w" },
  "pendingConfirmation": { "amount": 123000, "category": "FLEX_INTERNATIONAL", "description": "Order 4821" },
  "policy": { "actions": { "autoAction": "APPROVE" } }
}

Keep the payment’s _id — it is the {pixId} of every next step. pendingConfirmation holds what will be paid, and policy what your organization’s business policies say about it. Reference: Create a Pix payment

Step 2: Set the details, if any are missing

Confirming pays exactly what pendingConfirmation holds, so it needs the amount and the balance category. If you sent both at creation, skip this step. Otherwise — a QR code, or a create without category — set them:

curl -X PUT \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 123000,
    "category": "FLEX_INTERNATIONAL"
  }'

Unless the QR code has an open amount, amount must be the payment’s txnUpdatedAmount (a COBV charge scheduled for its due date may also pay its txnOriginalAmount). The answer carries an updated policy. Reference: Set a Pix payment’s details

Step 3: Confirm the payment

When policy.actions.autoAction is APPROVE, confirm the payment — with no body:

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}/confirm' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

A successful confirmation answers 200 with the payment CONFIRMED; it becomes PAID when the Pix network settles it, and receipt.endToEndId is the ID the recipient’s bank shows. If the payment is refused — for insufficient funds or a limit, for example — it becomes FAILED, with the reason in failReason, and you get the error. When autoAction is NONE, the payment needs approval: send it for approval instead of confirming it. With DENY, the policies refuse it. Reference: Confirm a Pix payment

Pay on a later day

Send scheduledAt (YYYY-MM-DD) when creating the payment, or with PUT, to pay on a later day. The confirmation then answers 201 with the schedule, and the payment becomes SCHEDULED; on that day a new payment is created and paid. The day’s payment doesn’t carry the custom fields: in an organization with a required transaction custom field, it fails. A QR code charge with a due date can only be paid today or on its due date, and only payments by Pix key or QR code can be scheduled — a payment by bank details for a later day is refused at confirmation.

Cancel a payment

A payment that wasn’t paid yet — REQUESTED, waiting for approval, or SCHEDULED — can be cancelled:

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}/cancel' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

Getting Started

Integration guides

Cards

PIX & payments

Accounts & wallets

Building your integration

Send a Pix payment

Flow

Step 1: Create the payment

Step 2: Set the details, if any are missing

Step 3: Confirm the payment

Pay on a later day

Cancel a payment

Next steps

Business policies and approvals

Charge with PIX

​Flow

​Step 1: Create the payment

​Step 2: Set the details, if any are missing

​Step 3: Confirm the payment

​Pay on a later day

​Cancel a payment

​Next steps

Business policies and approvals

Charge with PIX

Flow

Step 1: Create the payment

Step 2: Set the details, if any are missing

Step 3: Confirm the payment

Pay on a later day

Cancel a payment

Next steps