PIX (BR)

⚡ Pix Payments (Brazil)

ℹ️ For full request and response examples, refer to theAPI Reference.

Pix is a real-time payment method in Brazil, developed by the Central Bank. It allows instant fund transfers between accounts, available 24/7. Our API supports Pix with dynamic QR Code generation and webhook status tracking.

⚠️
Availability Notice
Pix support may vary depending on your account configuration and country. Please contact our support or your account manager to confirm availability for your integration.

📘 Key Concepts

Concept	Description
⚡ Pix Dynamic QR	A unique QR code is generated per transaction. The payer scans it to complete the payment instantly.
🔔 Webhooks	All changes to the charge status (created, paid, expired, refunded) will trigger webhook notifications to the merchant system.
🚫 Refunds	Pix refunds are supported through the same API. Refunds can be partial or full, as long as the original charge was successfully paid.

🇧🇷 Pix Transaction Flow

sequenceDiagram
    participant Buyer as 🧑 Payer
    participant Merchant as 🛒 Merchant Platform
    participant A55API as 🧩 a55 API
    participant PixProvider as 🏦 Pix Provider (CIP / SPI)

    Buyer->>Merchant: 1. Selects Pix as payment method
    Merchant->>A55API: 2. Sends transaction request with payer data
    A55API->>PixProvider: 3. Creates dynamic Pix charge
    PixProvider-->>A55API: 4. Returns Pix QR Code & transaction ID
    A55API-->>Merchant: 5. Returns Pix QR Code to display to buyer
    Buyer->>PixProvider: 6. Scans QR Code and pays via banking app
    PixProvider-->>A55API: 7. Notifies Pix payment success
    A55API-->>Merchant: 8. Sends webhook with status: paid

🧾 Sample Pix Payload

{
  "wallet_uuid": "00000000-0000-0000-0000-000000000000",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "João Silva",
  "payer_email": "[email protected]",
  "payer_tax_id": "39999999999",
  "payer_cell_phone": "5511988887777",
  "installment_value": 1,
  "items": [
    {
      "name": "Tênis Esportivo",
      "description": "Tênis para corrida",
      "quantity": 1,
      "total_amount": 1,
      "unit_amount": 1,
      "sku": "TNS-SPORT-2025",
      "code": "TS2025"
    }
  ],
  "payer_address": {
    "street": "Av. Paulista",
    "address_number": "1000",
    "complement": "Apto 42",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "country": "BR"
  },
  "currency": "BRL",
  "due_date": "2025-12-31T23:59:59Z",
  "description": "Compra via Pix",
  "type_charge": "pix",
  "webhook_url": "https://webhook-test.com/pix-status", 
  "redirect_url": "https://example.com/confirmation"
}

{
  "charge_uuid": "00000000-0000-0000-0000-000000000000",
  "local_currency": 1,
  "currency": "BRL",
  "usd_currency": 0.9,
  "eur_currency": 0.78,
  "type": "pix",
  "date": "2025-07-08",
  "description": "pix payment",
  "due_date": "2025-07-09",
  "status": "issued",
  "installment_count": 1,
  "installments": [
    {
      "local_currency": 5,
      "currency": "BRL",
      "usd_currency": 0.9,
      "eur_currency": 0.78,
      "due_date": "2025-07-09",
      "status": "issued",
      "installment_number": 1
    }
  ],
  "pix_payload": {
    "payload": "00020101021226880014br.gov.bcb.pix2566qrcode.example.com.br...",
    "qr_code": "iVBORw0KGgoAAAANSUhEUgAAAhIAAAISAQAAAACxRhsSAAAFCklEQVR4nO2dS26jShSGv3NB8hCkLMBLwTvIklpZU...",
    "expiration_date": "2025-07-08 18:28:46.146201"
  },
  "charge_payment_url": "https://pix.a55.tech/?charge_uuid=00000000-0000-0000-0000-000000000000"
}

🔄 Pix Status Lifecycle

Status	Description
`issued`	Pix QR code was generated, waiting payment.
`paid`	The payment was completed successfully.
`canceled`	The QR code expired without payment.
`refunded`	The payment was refunded.
`error`	There was an error in Pix charge generation.

Updated 3 months ago