Receber pagamentos

Checkout hospedado

Uma página de pagamento pronta, com PIX, cartão e boleto na mesma tela.

Uma página de pagamento pronta, hospedada por nós. Você cria o checkout, recebe uma URL e manda o cliente para lá — sem construir formulário, sem validar cartão, sem tratar QR Code.

Como funciona

Você cria o checkout

POST /v1/checkouts com o valor e os meios de pagamento aceitos. A resposta traz uma url.
O cliente paga na nossa página

Ele escolhe o meio, preenche os dados e conclui. PIX, cartão e boleto na mesma tela.
Você recebe o webhook

charge.paid chega no seu servidor com a cobrança completa. É aí que o pedido é liberado.
O cliente volta para o seu site

Se você informou return_url, ele é levado de volta depois de pagar.

Criar um checkout

POST/v1/checkouts

Requisição

curl -X POST https://novexfinance.com.br/api/v1/checkouts \
  -H "Authorization: Bearer $NOVEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-48219" \
  -d '{
    "title": "Pedido #48219",
    "description": "2 itens · entrega expressa",
    "amount": 12990,
    "payment_methods": ["pix", "credit_card", "boleto"],
    "reference": "48219",
    "return_url": "https://sualoja.com.br/pedido/48219/obrigado",
    "expires_in": 3600,
    "metadata": { "canal": "app-ios" }
  }'

$checkout = $novex->post('/checkouts', [
    'title'           => 'Pedido #48219',
    'description'     => '2 itens · entrega expressa',
    'amount'          => 12990,
    'payment_methods' => ['pix', 'credit_card', 'boleto'],
    'reference'       => '48219',
    'return_url'      => 'https://sualoja.com.br/pedido/48219/obrigado',
    'expires_in'      => 3600, // 1 hora
], 'pedido-48219');

header('Location: ' . $checkout['url']);

const checkout = await novex.post('/checkouts', {
  title: 'Pedido #48219',
  description: '2 itens · entrega expressa',
  amount: 12990,
  payment_methods: ['pix', 'credit_card', 'boleto'],
  reference: '48219',
  return_url: 'https://sualoja.com.br/pedido/48219/obrigado',
  expires_in: 3600, // 1 hora
}, { idempotencyKey: 'pedido-48219' });

res.redirect(checkout.url);

checkout = novex.post('/checkouts', {
    'title': 'Pedido #48219',
    'description': '2 itens · entrega expressa',
    'amount': 12990,
    'payment_methods': ['pix', 'credit_card', 'boleto'],
    'reference': '48219',
    'return_url': 'https://sualoja.com.br/pedido/48219/obrigado',
    'expires_in': 3600,  # 1 hora
}, idempotency_key='pedido-48219')

return redirect(checkout['url'])

Campos de entrada

Campo	Tipo	Descrição
`title`obrigatório	string	Nome do que está sendo cobrado. Aparece na página para o cliente.
`amount`obrigatório	inteiro	Valor em centavos. Mínimo `500` (R$ 5,00).
`description`opcional	string	Detalhe adicional exibido na página, até 500 caracteres.
`payment_methods`opcional	lista	Meios aceitos: `"pix"`, `"credit_card"`, `"boleto"`. Omitido, habilita os três.
`reference`opcional	string	Seu identificador. Volta na consulta e nos webhooks.
`return_url`opcional	string	Para onde o cliente volta depois de pagar. Precisa ser HTTPS.
`single_use`opcional	booleano	`true` (padrão): o link morre no primeiro pagamento. `false`: aceita vários pagamentos.
`expires_in`opcional	inteiro	Validade em segundos, até 90 dias. Padrão: 86400 (24h) para link de uso único; sem expiração para reutilizável. `0` desliga a expiração.
`metadata`opcional	objeto	Dados livres seus, até 30 chaves.

Consultar um checkout

GET/v1/checkouts/{id}

Depois de pago, o campo charge traz a cobrança gerada — com o meio que o cliente escolheu, o valor líquido e a data do pagamento:

Resposta 200

{
  "object": "checkout",
  "id": "chk_4b81de07a2f6c395e0d8",
  "status": "paid",
  "url": "https://novexfinance.com.br/pay/8f21ac09d4b7e35012fa",
  "amount": 12990,
  "title": "Pedido #48219",
  "reference": "48219",
  "payment_methods": [
    "pix",
    "credit_card",
    "boleto"
  ],
  "single_use": true,
  "paid_at": "2026-08-07T14:41:22-03:00",
  "charge": {
    "object": "charge",
    "id": "ch_9f2a71c4e8b35d06a147",
    "status": "paid",
    "amount": 12990,
    "payment_method": "pix",
    "net_amount": 12341,
    "paid_at": "2026-08-07T14:41:22-03:00"
  }
}

Status do checkout

Status	Significa
`open`	Aberto e pagável.
`paid`	Já teve um pagamento confirmado. Se for de uso único, está encerrado.
`expired`	Passou da data de expiração e não aceita mais pagamento.

Encerrar antes da hora

Pedido cancelado no seu sistema? Encerre o checkout para que ninguém pague por engano:

POST/v1/checkouts/{id}/expire

Requisição

curl -X POST https://novexfinance.com.br/api/v1/checkouts/chk_4b81de07a2f6c395e0d8/expire \
  -H "Authorization: Bearer $NOVEX_API_KEY"

Um checkout já pago não pode ser expirado — a resposta é 409 com checkout_already_paid.

Uso único ou reutilizável

	`single_use: true` (padrão)	`single_use: false`
Para que serve	Um pedido, um cliente, um pagamento.	Link de doação, mensalidade, cobrança recorrente do mesmo valor.
Depois do 1º pagamento	Encerra.	Continua aceitando.
Expiração padrão	24 horas.	Não expira.

Para pedido de e-commerce, use sempre uso único. Um link reutilizável compartilhado por engano aceitaria o pagamento de outra pessoa pelo mesmo pedido.

Listar checkouts

GET/v1/checkouts

Lista os checkouts criados pela API, do mais recente para o mais antigo. Aceita limit e offset — ver paginação.

Como funciona

Você cria o checkout

O cliente paga na nossa página

Você recebe o webhook