PIX Payment — Brazil

pix

PIX is the instant payment system created by the Central Bank of Brazil. It allows real-time fund transfers 24/7. This dedicated endpoint is optimized to generate Dynamic QR Codes with a configurable Time-to-Live (TTL). It returns an EMV payload for "Copy and Paste" and a direct image link for scanning.
information icon
Important: Unlike standard card payments, a successful request first returns a WAITING status. This means the QR code is active and awaits customer authorization in their banking environment.

Requirements

Before you call the PIX QR Code endpoint, make sure you have the following in place:

  • Authentication: Every request requires a Bearer Token generated via the Authentication endpoint.
  • PIX Key Activation: Your merchant account must have an active PIX key registered with Getnet.
  • Webhook Listener: You must have a public HTTPS endpoint ready to receive the PAYMENT_APPROVED notification to confirm the final settlement.

Characteristics

The following table summarizes the main capabilities of PIX.

CapabilityDetails
Customer ExperienceScan & Pay — Customers scan the QR Code image or use the "PIX Copia e Cola" string.
SettlementInstant — Once the customer authorizes the payment, funds settle in seconds.
ConfigurabilityDynamic TTL — You set the expiration in the x-qrcode-expiration-time header.
SecurityBiometric Auth — The customer authorizes the payment in their secure banking app.

Available features

The following table shows the countries and operations that PIX supports.

Payment FlowSupported CountriesPurchasesRefundsPartial RefundsPre-authorizations
Dedicated APIBrazil (BR)✅✅✅❌

Integration flow

The PIX QR Code flow is designed for immediate credential generation and asynchronous status updates.

1. Create the QR code request

Start the QR code generation by calling the dedicated PIX QR Code endpoint.

AttributeDescriptionRequired Value
x-qrcode-expiration-timeHeader: Defines TTL in seconds (e.g., 180 = 3 mins).Integer
amountTransaction amount in cents (e.g., 8900 for R$ 89,00)Integer
currencyISO currency codeBRL
order_idYour unique internal order identifierString
Sample Request:
Bash
curl --location --request POST 'https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments/qrcode/pix' \ --header 'x-qrcode-expiration-time: 180' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <ACCESS_TOKEN>' \ --data-raw '{ "amount": 8900, "currency": "BRL", "order_id": "ORDER-10187383", "customer_id": "customer_21081826", "idempotency_key": "1eb2412c-165a-41cd-b1d9-76c575d30a21" }'

2. Handle the response

The API returns the payment identifier and a nested additional_data object containing the QR code payload.
Sample Response:
JSON
{ "payment_id": "03ec0ede-3bc9-42dd-a71b-1c3a670b2b89", "status": "WAITING", "description": "QR Code successfully generated and awaiting payment.", "additional_data": { "transaction_id": "890005df15a2-0b1e-4c6e-8ece-11a71070be06", "qr_code": "00020101021226740014br.bcb.pix...", "creation_date_qrcode": "2026-01-15T18:55:55", "expiration_date_qrcode": "2026-01-15T18:58:58", "psp_code": "033" }, "idempotency_key": "e757d73e-fbdb-40ee-a72b-6f06f19c7a27" }
information icon
Note: Use the additional_data.qr_code string for the "Copia e Cola" (Copy and Paste) feature. If your frontend requires an image URL, use the Getnet CDN with the payment_id. You can also use the specific qr_code_image link, if provided.

3. Manage post-sale operations

After the customer pays, handle the confirmation and any refunds.

  • Webhook Confirmation: Once the bank clears the payment, you receive a notification at your callback_url. Update the order status to APPROVED only after receiving this event.
  • Refunds: PIX supports full or partial refunds for up to 90 days after the original payment.

On this page

PIX Payment — Brazil