> ## 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 funciona o recebimento de pagamentos via PIX

# PIX

> Receba pagamentos instantâneos através de QR Code e código copia e cola

O PIX é o método mais rápido para receber pagamentos na Velfy: você gera uma cobrança, o cliente paga em segundos pelo app do banco, e o valor cai na sua conta.

## Como funciona

<Steps>
  <Step title="Você cria a cobrança">
    Chama o endpoint de transações com `paymentMethod: "pix"` e o valor desejado.
  </Step>

  <Step title="Recebe o QR Code">
    A resposta traz o código copia e cola (payload EMV), pronto para ser exibido como QR Code ou colado no app do banco.
  </Step>

  <Step title="Cliente paga">
    O cliente escaneia o QR Code ou cola o código no app do banco dele.
  </Step>

  <Step title="Confirmação em tempo real">
    Assim que o PIX é compensado, você recebe a confirmação via [webhook](/guides/webhooks) e o valor fica disponível na sua conta Velfy.
  </Step>
</Steps>

## Exemplo rápido

```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,
    "postbackUrl": "https://sualoja.com/webhooks/velfy",
    "customer": {
      "name": "João da Silva",
      "email": "joao@example.com",
      "document": { "type": "cpf", "number": "12345678900" }
    },
    "items": [
      { "title": "Curso Online", "unitPrice": 10000, "quantity": 1, "tangible": false }
    ]
  }'
```

A resposta traz o campo `pix.qrcode` (o código copia e cola) — use-o para gerar a imagem do QR Code ou exiba diretamente para o cliente copiar.

## Ciclo de vida da cobrança

| Status     | O que significa                           |
| ---------- | ----------------------------------------- |
| `pending`  | Aguardando o pagamento — exiba o QR Code  |
| `paid`     | PIX compensado — libere o produto/serviço |
| `refunded` | Valor estornado ao pagador                |

## Boas práticas

* Defina um prazo de expiração (`pix.expiresInDays`) coerente com o seu produto
* Use `externalRef` para relacionar a cobrança com o pedido no seu sistema
* Não dependa apenas de polling — configure `postbackUrl` para receber a confirmação em tempo real

## Próximos passos

<CardGroup cols={2}>
  <Card title="Referência técnica" icon="book" href="/api-reference/payments/pix">
    Veja todos os campos e o exemplo completo de resposta
  </Card>

  <Card title="Cartão de Crédito" icon="credit-card" href="/guides/credit-card">
    Aceite também pagamentos com cartão
  </Card>
</CardGroup>