Receber pagamentos

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

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

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

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;

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

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

// 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">';

import QRCode from 'qrcode';

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

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.