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

# PIX

> Como gerar uma cobrança PIX

# PIX

> Receba pagamentos PIX de forma instantânea através de QR Codes

O método `pix` permite gerar cobranças instantâneas com QR Code e código copia e cola. Ideal para vendas online e qualquer situação onde você precisa receber um pagamento rapidamente.

## 🚀 Como Funciona

<CardGroup cols={2}>
  <Card title="📱 QR Code gerado" color="#631286" icon="qrcode">
    Você cria a cobrança e recebe um QR Code e código copia e cola
  </Card>

  <Card title="💳 Cliente paga" color="#631286" icon="credit-card">
    O cliente escaneia o QR Code ou cola o código no app do banco
  </Card>

  <Card title="⚡ Confirmação instantânea" color="#631286" icon="bolt">
    Você recebe a confirmação via webhook assim que o PIX é compensado
  </Card>

  <Card title="💰 Saldo disponível" color="#631286" icon="money-bill">
    O valor fica disponível na sua conta Velfy
  </Card>
</CardGroup>

## 🛠️ Implementação Rápida

### 1. Criar a cobrança PIX

```bash theme={null}
curl -X POST 'https://api.velfy.com/api/v1/transactions' \
  -u "sk_xxx:pk_xxx" \
  -H 'Content-Type: application/json' \
  -d '{
    "paymentMethod": "pix",
    "amount": 10000,
    "externalRef": "pedido-123",
    "postbackUrl": "https://sualoja.com/webhooks/velfy",
    "pix": {
      "expiresInDays": 2
    },
    "customer": {
      "name": "João da Silva",
      "email": "joao@example.com",
      "phone": "11999998888",
      "document": {
        "type": "cpf",
        "number": "12345678900"
      }
    },
    "items": [
      {
        "title": "Curso Online",
        "unitPrice": 10000,
        "quantity": 1,
        "tangible": false
      }
    ]
  }'
```

### 2. Resposta com QR Code

```json theme={null}
{
  "success": true,
  "message": "Transaction created",
  "status": 201,
  "data": {
    "id": 918234,
    "status": "pending",
    "amount": 10000,
    "paymentMethod": "pix",
    "acquirerType": "woovi",
    "secureId": "9c1a9b2e-7c3d-4e11-9a2f-3a1c5f0e9d21",
    "secureUrl": "https://pay.velfy.com/checkout/9c1a9b2e-7c3d-4e11-9a2f-3a1c5f0e9d21",
    "externalId": "pedido-123",
    "pix": {
      "qrcode": "00020126580014br.gov.bcb.pix0136...6304ABCD",
      "expirationDate": "2026-07-30T12:00:00.000Z"
    },
    "fees": 350,
    "postbackUrl": "https://sualoja.com/webhooks/velfy",
    "createdAt": "2026-07-28T12:00:00.000Z"
  }
}
```

### 3. Exibir o QR Code para o cliente

```html theme={null}
{/* Gere a imagem do QR Code a partir do payload EMV */}
<img src="data:image/png;base64,..." alt="QR Code PIX" />

{/* Ou disponibilize o código copia e cola */}
<div class="pix-code">
  <p>Copie e cole no app do seu banco:</p>
  <input type="text" value="00020126580014br.gov.bcb.pix..." readonly />
</div>
```

## 📊 Parâmetros Detalhados

### Campo específico do PIX

| Campo               | Tipo     | Descrição                                             |
| ------------------- | -------- | ----------------------------------------------------- |
| `pix.expiresInDays` | `number` | Prazo de expiração da cobrança, em dias (padrão: `2`) |

<Info>
  Consulte os [campos comuns a toda transação](/api-reference/payments/transactions) para os demais parâmetros (`amount`, `customer`, `items`, etc).
</Info>

## 📋 Status da Transação

| Status     | Descrição                  | Próximo Passo                  |
| ---------- | -------------------------- | ------------------------------ |
| `pending`  | Aguardando pagamento       | Exiba o QR Code para o cliente |
| `paid`     | PIX compensado com sucesso | Libere o produto/serviço       |
| `refunded` | Estornado                  | Valor devolvido ao pagador     |

## 🛡️ Boas Práticas

<AccordionGroup>
  <Accordion title="🔒 Validação de dados" icon="shield-check">
    * Valide CPF/CNPJ antes de enviar a requisição
    * Confirme que o valor de `amount` corresponde à soma dos itens
    * Use HTTPS em todas as chamadas
  </Accordion>

  <Accordion title="🔄 Idempotência" icon="arrows-rotate">
    * Use `externalRef` para relacionar a cobrança com seu pedido interno
    * Trate reenvios de webhook de forma idempotente
  </Accordion>

  <Accordion title="📊 Monitoramento" icon="chart-line">
    * Acompanhe o tempo até a confirmação de pagamento
    * Configure `postbackUrl` para não depender apenas de polling
  </Accordion>
</AccordionGroup>

***

## 🎯 Próximos Passos

<CardGroup cols={2}>
  <Card title="🔗 Configurar Webhooks" color="#631286" icon="webhook" href="/api-reference/payments/webhooks">
    Receba a confirmação do pagamento automaticamente
  </Card>

  <Card title="💳 Cartão de Crédito" color="#631286" icon="credit-card" href="/api-reference/payments/credit-card">
    Aceite também pagamentos com cartão
  </Card>
</CardGroup>