# PIX API

The PIX API enables sending and receiving instant payments via Brazil's PIX system.

## Overview

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/pix/charges` | POST | Create a PIX charge (receive payment) |
| `/api/v1/pix/charges/:id` | GET | Get charge details |
| `/api/v1/pix/payouts` | POST | Create a PIX payout (send payment) |
| `/api/v1/pix/payouts/:id` | GET | Get payout details |
| `/api/v1/pix/dict/:key` | GET | Look up a PIX key in DICT |
| `/api/v1/pix/qrcode` | POST | Generate a PIX QR code |

## PIX In (Receiving Payments)

### Create a Charge

```http
POST /api/v1/pix/charges
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 15000,
  "description": "Order #12345",
  "payer": {
    "document": "12345678901",
    "name": "Maria Silva"
  },
  "expiration": 3600,
  "metadata": {
    "order_id": "12345",
    "customer_id": "cust_abc"
  }
}
```

::: tip
Amounts are always in **centavos** (smallest currency unit). R$ 150.00 = `15000`.
:::

**Response:**

```json
{
  "data": {
    "id": "chg_01HQGX...",
    "status": "pending",
    "amount": 15000,
    "description": "Order #12345",
    "pix_key": "pix@fluxiq.com.br",
    "qr_code": "00020126580014br.gov.bcb.pix...",
    "qr_code_image": "data:image/png;base64,...",
    "expiration": "2026-02-03T13:00:00Z",
    "created_at": "2026-02-03T12:00:00Z"
  }
}
```

### Charge Statuses

| Status | Description |
|--------|-------------|
| `pending` | Awaiting payment |
| `paid` | Payment received and confirmed |
| `expired` | Charge expired without payment |
| `cancelled` | Charge cancelled by merchant |
| `refunded` | Payment was refunded |

## PIX Out (Sending Payments)

### Create a Payout

```http
POST /api/v1/pix/payouts
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 5000,
  "description": "Supplier payment",
  "recipient": {
    "pix_key": "supplier@company.com",
    "pix_key_type": "email"
  },
  "idempotency_key": "payout_20260203_001"
}
```

::: warning
Always include an `idempotency_key` to prevent duplicate payouts. The same key within 30 days will return the original response.
:::

**Response:**

```json
{
  "data": {
    "id": "pay_01HQGX...",
    "status": "processing",
    "amount": 5000,
    "recipient": {
      "pix_key": "supplier@company.com",
      "pix_key_type": "email",
      "name": "Empresa XYZ LTDA",
      "document": "12345678000190",
      "bank": "Nubank",
      "ispb": "18236120"
    },
    "idempotency_key": "payout_20260203_001",
    "created_at": "2026-02-03T12:00:00Z"
  }
}
```

### Payout Statuses

| Status | Description |
|--------|-------------|
| `processing` | Payout submitted to provider |
| `confirmed` | Payment confirmed by BACEN |
| `failed` | Payment failed (insufficient funds, invalid key, etc.) |
| `cancelled` | Payout cancelled before processing |
| `returned` | Payment returned by recipient bank |

## DICT Lookup

Look up a PIX key to verify the recipient before sending:

```http
GET /api/v1/pix/dict/supplier@company.com
Authorization: Bearer {token}
```

**Response:**

```json
{
  "data": {
    "key": "supplier@company.com",
    "key_type": "email",
    "account": {
      "participant_ispb": "18236120",
      "participant_name": "Nubank",
      "branch": "0001",
      "account_number": "12345678",
      "account_type": "checking"
    },
    "owner": {
      "name": "Empresa XYZ LTDA",
      "document": "12345678000190",
      "document_type": "cnpj"
    }
  }
}
```

### PIX Key Types

| Type | Format | Example |
|------|--------|---------|
| `cpf` | 11 digits | `12345678901` |
| `cnpj` | 14 digits | `12345678000190` |
| `email` | Email address | `pix@company.com` |
| `phone` | +55 + DDD + number | `+5511999999999` |
| `evp` | UUID v4 | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

## QR Code Generation

```http
POST /api/v1/pix/qrcode
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "dynamic",
  "amount": 15000,
  "description": "Order #12345",
  "expiration": 3600
}
```

**Response:**

```json
{
  "data": {
    "type": "dynamic",
    "payload": "00020126580014br.gov.bcb.pix...",
    "image_base64": "data:image/png;base64,...",
    "image_url": "https://api.fluxiq.com.br/qr/chg_01HQGX.png"
  }
}
```

## Webhooks

PIX events are delivered via webhooks. See [Webhooks](/api/webhooks) for configuration.

| Event | Description |
|-------|-------------|
| `pix.charge.paid` | A charge was paid |
| `pix.charge.expired` | A charge expired |
| `pix.payout.confirmed` | A payout was confirmed |
| `pix.payout.failed` | A payout failed |
| `pix.payout.returned` | A payout was returned |
| `pix.refund.completed` | A refund was completed |

## Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `INSUFFICIENT_FUNDS` | 422 | Account balance too low for payout |
| `INVALID_PIX_KEY` | 422 | PIX key not found in DICT |
| `DUPLICATE_PAYOUT` | 409 | Idempotency key already used |
| `AMOUNT_TOO_LOW` | 422 | Amount below minimum (R$ 0.01) |
| `AMOUNT_TOO_HIGH` | 422 | Amount exceeds daily limit |
| `CHARGE_EXPIRED` | 410 | Charge has expired |
| `PROVIDER_ERROR` | 502 | PIX provider returned an error |