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

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:

{
  "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

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:

{
  "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:

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

Response:

{
  "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

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

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

Response:

{
  "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 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