# Pix Payment — Brazil

![pix](https://static-devportal-ux.sensedia-eng.com/Pagonxt/staging/documentations/pixlogo-1768587458545-3hhfi70b.png)

Pix is the instant payment system created by the Central Bank of Brazil, allowing for real-time fund transfers 24/7. This dedicated endpoint is optimized for generating **Dynamic QR Codes** with a configurable Time-to-Live (TTL), returning an EMV payload for "Copy and Paste" and a direct image link for scanning.

<Callout type="warning">

Unlike standard card payments, the initial success of this request returns a **`WAITING`** status. This indicates the QR code is active and awaiting customer authorization in their banking environment.

</Callout>

## Requirements

Before calling the Pix QR Code endpoint, ensure the following are configured:

* **Authentication:** A **Bearer Token** generated via the [Authentication endpoint](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/authentication) is mandatory for every request.
* **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

| Capability              | Details                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| **Customer Experience** | **Scan & Pay** — Customers scan the QR Code image or use the "Pix Copia e Cola" string.   |
| **Settlement**          | **Instant** — Once the customer authorizes the payment, funds are settled in seconds.     |
| **Configurability**     | **Dynamic TTL** — Expiration is managed via the `x-qrcode-expiration-time` header.        |
| **Security**            | **Biometric Auth** — Authorization is performed within the customer's secure banking app. |

## Available Features

| Payment Flow  | Supported Countries | Purchases | Refunds | Partial Refunds | Pre-authorizations |
| ------------- | ------------------- | --------- | ------- | --------------- | ------------------ |
| Dedicated API | Brazil (BR)         | ✅         | ✅       | ✅               | ❌                  |

## Integration Flow

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

![Pix ](https://static-devportal-ux.sensedia-eng.com/Pagonxt/staging/documentations/pix-flow-1768587340725-h4otmmfa.png)

## 1. Create the QR Code Request

Initiate the QR code generation by calling the dedicated [Pix QR Code endpoint](https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments/qrcode/pix).

| Attribute                      | Description                                               | Required Value |
| ------------------------------ | --------------------------------------------------------- | -------------- |
| **`x-qrcode-expiration-time`** | **Header**: Defines TTL in seconds (e.g., 180 \= 3 mins). | Integer        |
| **`amount`**                   | Transaction amount in cents (e.g., `8900` for R\$ 89,00)   | Integer        |
| **`currency`**                 | ISO currency code                                         | `BRL`          |
| **`order_id`**                 | Your unique internal order identifier                     | String         |

**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. Handling 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"
}

```

<Callout type="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` or the specific `qr_code_image` link if provided.

</Callout>

## 3. Post-sale Operations

* **Webhook Confirmation:** Once the bank clears the payment, a notification will be sent to 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.