# Primeira cobrança

Passo a passo do zero ao PIX pago, com código pronto para copiar.

Um roteiro completo: da chave até o pagamento confirmado no seu sistema. Se seguir os quatro passos, no fim você terá um PIX real sendo cobrado e um webhook chegando no seu servidor.

### Guarde a chave no ambiente

Gere a chave em [API Keys](https://novexfinance.com.br/app/api-keys) e coloque numa variável de ambiente. Ela nunca deve aparecer no código.

_Ambiente_

```bash
# .env do seu projeto (fora do Git)
NOVEX_API_KEY=nvx_live_7d3f9a21c48e6b05d7f1a93c2e84b60d5a71f39c8e04b2d6
NOVEX_API_URL=https://novexfinance.com.br/api/v1
```

---

### Confirme que a chave funciona

Antes de escrever qualquer lógica, faça o ping. Se ele não passar, nada mais vai passar.

_Requisição_

```bash
curl https://novexfinance.com.br/api/v1/ping \
  -H "Authorization: Bearer $NOVEX_API_KEY"
```

Esperado: `200` com `"authenticated": true`. Recebeu `403 kyc_required`? A chave está certa, mas a verificação de identidade ainda não foi aprovada — conclua no painel antes de seguir.

---

### Crie a cobrança PIX

Valores **sempre em centavos**: `12990` é R$ 129,90. O mínimo é `500` (R$ 5,00).

_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
$payload = [
    'payment_method' => 'pix',
    'amount'         => 12990, // centavos
    'description'    => 'Pedido #48219',
    'reference'      => '48219',
    'customer'       => [
        'name'     => 'Maria Oliveira',
        'email'    => 'maria@exemplo.com.br',
        'phone'    => '11987654321',
        'document' => '39053344705',
    ],
];

$ch = curl_init(getenv('NOVEX_API_URL') . '/charges');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 40,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('NOVEX_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: pedido-48219',
    ],
]);

$charge = json_decode(curl_exec($ch), true);
curl_close($ch);

// código copia e cola do PIX
echo $charge['pix']['qr_code'];
```

```js
const res = await fetch(`${process.env.NOVEX_API_URL}/charges`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.NOVEX_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'pedido-48219',
  },
  body: JSON.stringify({
    payment_method: 'pix',
    amount: 12990, // centavos
    description: 'Pedido #48219',
    reference: '48219',
    customer: {
      name: 'Maria Oliveira',
      email: 'maria@exemplo.com.br',
      phone: '11987654321',
      document: '39053344705',
    },
  }),
});

const charge = await res.json();
console.log(charge.pix.qr_code); // copia e cola
```

```python
import os, requests

res = requests.post(
    f'{os.environ["NOVEX_API_URL"]}/charges',
    headers={
        'Authorization': f'Bearer {os.environ["NOVEX_API_KEY"]}',
        'Idempotency-Key': 'pedido-48219',
    },
    json={
        'payment_method': 'pix',
        'amount': 12990,  # centavos
        'description': 'Pedido #48219',
        'reference': '48219',
        'customer': {
            'name': 'Maria Oliveira',
            'email': 'maria@exemplo.com.br',
            'phone': '11987654321',
            'document': '39053344705',
        },
    },
    timeout=40,
)

charge = res.json()
print(charge['pix']['qr_code'])
```

A resposta `201` traz o código copia e cola em `pix.qr_code`. Guarde o `id` — é por ele que você consulta a cobrança depois.

_Resposta 201_

```json
{
  "object": "charge",
  "id": "ch_9f2a71c4e8b35d06a147",
  "status": "pending",
  "amount": 12990,
  "currency": "BRL",
  "payment_method": "pix",
  "description": "Pedido #48219",
  "reference": "48219",
  "pix": {
    "qr_code": "00020126580014BR.GOV.BCB.PIX0136…5204000053039865802BR6009SAO PAULO62070503***6304A1B2",
    "expires_at": "2026-08-08T14:32:10-03:00"
  },
  "created_at": "2026-08-07T14:32:10-03:00"
}
```

> ℹ️ O `qr_code` é o **código copia e cola** (payload EMV). Para mostrar a imagem do QR, gere-a a partir dessa string com qualquer biblioteca de QR Code no seu lado — assim você controla tamanho, cor e formato.

---

### Receba a confirmação

Não fique perguntando à API se pagou. Cadastre um webhook uma vez e nós avisamos no instante em que o pagamento entra.

_Cadastrar webhook_

```bash
curl -X POST https://novexfinance.com.br/api/v1/webhooks \
  -H "Authorization: Bearer $NOVEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://sualoja.com.br/webhooks/novex",
    "events": "all"
  }'
```

Guarde o `secret` devolvido: é ele que valida a assinatura de cada evento. O passo a passo da validação está em [Webhooks](https://novexfinance.com.br/docs/webhooks).

> ⚠️ **Não dá para receber webhook agora** (ambiente local, sem URL pública)? Consulte a cobrança com `GET /v1/charges/{id}` enquanto desenvolve — mas troque por webhook antes de ir para produção. Consulta em laço não escala e atrasa a confirmação para o seu cliente.

---

## E agora

- [Boleto](https://novexfinance.com.br/docs/boleto) — Mesma chamada, outro meio: linha digitável e código de barras.
- [Cartão](https://novexfinance.com.br/docs/cartao) — Receber por cartão sem precisar de certificação PCI-DSS.
- [Convenções](https://novexfinance.com.br/docs/convencoes) — Idempotência, paginação, limites e formato de datas.
- [Erros](https://novexfinance.com.br/docs/erros) — O que cada código significa e como reagir.


---

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