Comece por aqui

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 e coloque numa variável de ambiente. Ela nunca deve aparecer no código.

Ambiente

# .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
```
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

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"
    }
  }'

$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'];

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

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

{
  "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
```
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.

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

BoletoMesma chamada, outro meio: linha digitável e código de barras. CartãoReceber por cartão sem precisar de certificação PCI-DSS. ConvençõesIdempotência, paginação, limites e formato de datas. ErrosO que cada código significa e como reagir.

Guarde a chave no ambiente

Confirme que a chave funciona

Crie a cobrança PIX

Receba a confirmação

E agora