# PIX

Cobrança com QR Code e copia e cola, com confirmação em segundos.

Cobrança PIX com código copia e cola. O cliente paga em segundos e a confirmação chega no seu servidor por webhook, sem intervenção.

`POST /v1/charges`

## Criar a cobrança

_Requisição_

```bash
curl -X POST https://novexfinance.com.br/api/v1/charges \
  -H "Authorization: Bearer $NOVEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-48219" \
  -d '{
    "payment_method": "pix",
    "amount": 12990,
    "description": "Pedido #48219",
    "reference": "48219",
    "customer": {
      "name": "Maria Oliveira",
      "email": "maria@exemplo.com.br",
      "phone": "11987654321",
      "document": "39053344705"
    }
  }'
```

```php
$charge = $novex->post('/charges', [
    'payment_method' => 'pix',
    'amount'         => 12990,
    'description'    => 'Pedido #48219',
    'reference'      => '48219',
    'customer'       => [
        'name'     => 'Maria Oliveira',
        'email'    => 'maria@exemplo.com.br',
        'phone'    => '11987654321',
        'document' => '39053344705',
    ],
], 'pedido-48219');

// string do copia e cola
$copiaECola = $charge['pix']['qr_code'];
```

```js
const charge = await novex.post('/charges', {
  payment_method: 'pix',
  amount: 12990,
  description: 'Pedido #48219',
  reference: '48219',
  customer: {
    name: 'Maria Oliveira',
    email: 'maria@exemplo.com.br',
    phone: '11987654321',
    document: '39053344705',
  },
}, { idempotencyKey: 'pedido-48219' });

const copiaECola = charge.pix.qr_code;
```

```python
charge = novex.post('/charges', {
    'payment_method': 'pix',
    'amount': 12990,
    'description': 'Pedido #48219',
    'reference': '48219',
    'customer': {
        'name': 'Maria Oliveira',
        'email': 'maria@exemplo.com.br',
        'phone': '11987654321',
        'document': '39053344705',
    },
}, idempotency_key='pedido-48219')

copia_e_cola = charge['pix']['qr_code']
```

### Campos de entrada

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `payment_method` obrigatório | string | Use `"pix"`. |
| `amount` obrigatório | inteiro | Valor em **centavos**. Mínimo `500` (R$ 5,00). |
| `description` opcional | string | Descrição da cobrança, até 200 caracteres. Padrão: `"Cobrança"`. |
| `reference` opcional | string | Seu identificador (número do pedido). Volta em consultas e webhooks e serve de filtro. |
| `metadata` opcional | objeto | Dados livres seus, até 30 chaves. Devolvido intacto. |
| `customer.name` obrigatório | string | Nome completo do pagador. Mínimo 3 caracteres. |
| `customer.email` obrigatório | string | E-mail válido. |
| `customer.phone` obrigatório | string | DDD + número, só dígitos (10 ou 11). Aceita o `55` na frente. |
| `customer.document` obrigatório | string | CPF (11 dígitos) ou CNPJ (14). Validamos o dígito verificador. |

## Resposta

_Resposta 201_

```json
{
  "object": "charge",
  "id": "ch_9f2a71c4e8b35d06a147",
  "status": "pending",
  "amount": 12990,
  "currency": "BRL",
  "payment_method": "pix",
  "description": "Pedido #48219",
  "reference": "48219",
  "customer": {
    "name": "Maria Oliveira",
    "email": "maria@exemplo.com.br",
    "phone": "11987654321",
    "document": "39053344705",
    "document_type": "cpf"
  },
  "fee_amount": null,
  "net_amount": null,
  "available_at": null,
  "paid_at": null,
  "created_at": "2026-08-07T14:32:10-03:00",
  "metadata": [],
  "pix": {
    "qr_code": "00020126580014BR.GOV.BCB.PIX0136…5204000053039865802BR6009SAO PAULO62070503***6304A1B2",
    "expires_at": "2026-08-08T14:32:10-03:00"
  }
}
```

| Campo da resposta | Tipo | Descrição |
| --- | --- | --- |
| `pix.qr_code` opcional | string | Código **copia e cola** (payload EMV). É o que o cliente cola no aplicativo do banco. |
| `pix.expires_at` opcional | data | Quando o código deixa de ser pago. |
| `fee_amount` opcional | inteiro | Taxa cobrada, em centavos. Preenchida só quando a cobrança é paga. |
| `net_amount` opcional | inteiro | Valor líquido que entra no seu saldo (bruto − taxa). |
| `available_at` opcional | data | Quando o valor fica disponível para saque. No PIX, é imediato. |

## Exibir o QR Code

Devolvemos a **string** do copia e cola, não uma imagem. Isso é intencional: gerando o QR do seu lado, você controla tamanho, cor, margem e formato, e não depende de baixar uma imagem nossa para renderizar a sua tela.

Ofereça sempre as duas opções ao cliente — a imagem do QR para quem paga pelo celular e um botão de copiar para quem paga pelo computador.

_Gerar a imagem_

```php
// com endroid/qr-code, por exemplo
$qr = Builder::create()
    ->data($charge['pix']['qr_code'])
    ->size(300)
    ->build();

echo '<img src="' . $qr->getDataUri() . '" alt="QR Code PIX">';
```

```js
import QRCode from 'qrcode';

const dataUrl = await QRCode.toDataURL(charge.pix.qr_code, {
  width: 300,
  margin: 1,
});
```

```python
import qrcode

img = qrcode.make(charge['pix']['qr_code'])
img.save('pix.png')
```

## Ciclo de vida

| Status | Significa | O que fazer |
| --- | --- | --- |
| `pending` | Cobrança criada, aguardando o pagamento. | Mostrar o QR/copia e cola ao cliente. |
| `paid` | Pagamento confirmado. | Liberar o pedido. Chega por webhook `charge.paid`. |
| `refunded` | Valor devolvido ao pagador. | Reverter a liberação. |
| `failed` | A cobrança não pôde ser concluída. | Criar uma nova, se o cliente ainda quiser pagar. |

> 🚫 **Só libere o pedido em `paid`.** Um código PIX gerado não é pagamento — é convite para pagar. Enquanto o status for `pending`, nada entrou.

## Liquidação

No PIX o valor fica disponível para saque **assim que o pagamento é confirmado**. O campo `available_at` volta com a mesma data de `paid_at`, e o valor já entra no `available` do [saldo](https://novexfinance.com.br/docs/saldo-e-saques).


---

Documentação completa: https://novexfinance.com.br/docs/pix
Base da API: https://novexfinance.com.br/api/v1