> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /pix-qr

> Generate PIX Copia e Cola strings and QR codes for instant Brazilian payments.

## Endpoint

```
POST https://api.bunny.build/api/v1/pix-qr
```

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

Generate valid PIX Copia e Cola strings and scannable QR codes for the Brazilian instant payment system. Provide a PIX key, beneficiary name, city, and optional amount to receive a fully compliant payload and a base64-encoded QR code image ready to embed in your checkout, invoice, or receipt.

## Use cases

* Embed a PIX QR code in e-commerce checkout pages for instant payment
* Generate donation form links for nonprofits and campaigns
* Automate invoice generation with unique transaction IDs
* Enable peer-to-peer payment flows in fintech applications

## Request body

| Field         | Type   | Required | Description                                             |
| ------------- | ------ | -------- | ------------------------------------------------------- |
| `key`         | string | Yes      | PIX key: phone number, CPF, email, or EVP (random key)  |
| `name`        | string | Yes      | Beneficiary name (max 25 characters)                    |
| `city`        | string | Yes      | Beneficiary city (max 15 characters)                    |
| `amount`      | number | No       | Payment amount in BRL. Omit for open-value transactions |
| `description` | string | No       | Transaction description (max 72 characters)             |
| `txid`        | string | No       | Transaction ID for reconciliation                       |

### Example

```json theme={null}
{
  "key": "11999887766",
  "name": "Bunny Build",
  "city": "Sao Paulo",
  "amount": 10.00
}
```

## Response

### 200 OK

| Field       | Type   | Description                          |
| ----------- | ------ | ------------------------------------ |
| `payload`   | string | PIX Copia e Cola string (EMV format) |
| `qr_base64` | string | Base64-encoded PNG QR code image     |
| `mime_type` | string | MIME type of the QR code image       |
| `key`       | string | PIX key used                         |
| `name`      | string | Beneficiary name                     |
| `city`      | string | Beneficiary city                     |
| `amount`    | number | Amount in BRL, if provided           |

**Example**

```json theme={null}
{
  "payload": "00020126330014BR.GOV.BCB.PIX0111119998877665204000053039865406100.005802BR5911Bunny Build6009Sao Paulo62070503***6304ABCD",
  "qr_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mime_type": "image/png",
  "key": "11999887766",
  "name": "Bunny Build",
  "city": "Sao Paulo",
  "amount": 10.00
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Fields 'key', 'name', and 'city' are required."
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/pix-qr \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"key": "11999887766", "name": "Bunny Build", "city": "Sao Paulo", "amount": 10.00}'
```