Receber pagamentos

Cartão de crédito

Checkout hospedado (sem PCI-DSS) e cobrança direta para quem é certificado.

Há dois jeitos de receber por cartão. A diferença não é técnica — é regulatória: quem recebe número de cartão no próprio servidor precisa ser certificado PCI-DSS.

Checkout hospedado — recomendado Nós exibimos o formulário. O número do cartão nunca chega ao seu servidor, e a certificação PCI-DSS não se aplica a você. Cobrança direta Você envia os dados do cartão pela API. Exige certificação PCI-DSS válida e liberação prévia da conta.

Checkout hospedado

Você cria o checkout, recebe uma URL e redireciona o cliente. A tela de pagamento é nossa, hospedada em https://novexfinance.com.br, e já vem com validação, parcelamento e confirmação prontos.

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",
    "amount": 12990,
    "payment_methods": ["credit_card", "pix"],
    "reference": "48219",
    "return_url": "https://sualoja.com.br/pedido/48219/obrigado"
  }'

$checkout = $novex->post('/checkouts', [
    'title'           => 'Pedido #48219',
    'amount'          => 12990,
    'payment_methods' => ['credit_card', 'pix'],
    'reference'       => '48219',
    'return_url'      => 'https://sualoja.com.br/pedido/48219/obrigado',
], 'pedido-48219');

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

const checkout = await novex.post('/checkouts', {
  title: 'Pedido #48219',
  amount: 12990,
  payment_methods: ['credit_card', 'pix'],
  reference: '48219',
  return_url: 'https://sualoja.com.br/pedido/48219/obrigado',
}, { idempotencyKey: 'pedido-48219' });

res.redirect(checkout.url);

checkout = novex.post('/checkouts', {
    'title': 'Pedido #48219',
    'amount': 12990,
    'payment_methods': ['credit_card', 'pix'],
    'reference': '48219',
    'return_url': 'https://sualoja.com.br/pedido/48219/obrigado',
}, idempotency_key='pedido-48219')

return redirect(checkout['url'])

Resposta 201

{
  "object": "checkout",
  "id": "chk_4b81de07a2f6c395e0d8",
  "status": "open",
  "url": "https://novexfinance.com.br/pay/8f21ac09d4b7e35012fa",
  "amount": 12990,
  "currency": "BRL",
  "title": "Pedido #48219",
  "reference": "48219",
  "payment_methods": [
    "pix",
    "credit_card"
  ],
  "single_use": true,
  "return_url": "https://sualoja.com.br/pedido/48219/obrigado",
  "expires_at": "2026-08-08T14:32:10-03:00",
  "paid_at": null,
  "created_at": "2026-08-07T14:32:10-03:00",
  "charge": null
}

Detalhes completos do checkout — campos, expiração, reuso — em Checkout hospedado.

Confirme pelo webhook, não pelo retorno. A return_url é para onde o cliente volta depois de pagar; ela indica que ele terminou o fluxo, não que o pagamento foi aprovado. Quem confirma é o evento charge.paid.

Cobrança direta

Este caminho vem desabilitado. Enviar número de cartão pela API só é liberado para contas com certificação PCI-DSS válida — fale com o suporte comercial antes de integrar. Sem a liberação, a chamada responde 403 com card_direct_not_enabled.

Com a conta liberada, o cartão vira mais um payment_method em POST /v1/charges, com um objeto card a mais:

POST/v1/charges

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": "credit_card",
    "amount": 12990,
    "installments": 3,
    "description": "Pedido #48219",
    "reference": "48219",
    "customer": {
      "name": "Maria Oliveira",
      "email": "maria@exemplo.com.br",
      "phone": "11987654321",
      "document": "39053344705"
    },
    "card": {
      "number": "4111111111111111",
      "holder_name": "MARIA OLIVEIRA",
      "holder_document": "39053344705",
      "expiration_month": 8,
      "expiration_year": 29,
      "cvv": "123"
    }
  }'

Campo	Tipo	Descrição
`installments`opcional	inteiro	Número de parcelas, de 1 a 12. Padrão: 1.
`card.number`obrigatório	string	Número do cartão, 13 a 19 dígitos. Pontuação é ignorada.
`card.holder_name`obrigatório	string	Nome impresso no cartão.
`card.holder_document`obrigatório	string	CPF ou CNPJ do titular do cartão.
`card.expiration_month`obrigatório	inteiro	Mês de validade, de 1 a 12. Envie como número — `8`, não `"08"`.
`card.expiration_year`obrigatório	inteiro	Ano de validade com 2 dígitos — `29` para 2029.
`card.cvv`obrigatório	string	Código de segurança, 3 ou 4 dígitos.

Resposta 201

{
  "object": "charge",
  "id": "ch_c3947f10ba62d85e04c1",
  "status": "paid",
  "amount": 12990,
  "currency": "BRL",
  "payment_method": "credit_card",
  "reference": "48219",
  "fee_amount": 649,
  "net_amount": 12341,
  "available_at": "2026-09-06T14:35:02-03:00",
  "paid_at": "2026-08-07T14:35:02-03:00",
  "created_at": "2026-08-07T14:35:01-03:00",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "installments": 3
  }
}

Cartão recusado

Diferente de PIX e boleto, o cartão é decidido na hora. Quando o emissor não autoriza, a resposta é 402:

Resposta 402

{
  "error": {
    "code": "payment_refused",
    "message": "Pagamento não autorizado pelo emissor do cartão. Oriente o cliente a tentar outro cartão ou outra forma de pagamento.",
    "request_id": "a3f1c09b7e42d85610fb2c7d9a4e5b83"
  }
}

Nunca registre número de cartão ou CVV — nem em log, nem em banco, nem em arquivo temporário. Guardar CVV é vedado pelo PCI-DSS em qualquer circunstância, inclusive criptografado. Do nosso lado, esses campos são removidos antes de qualquer gravação.

Liquidação

Pagamentos com cartão liquidam em D+30 corridos a partir da aprovação. Até lá o valor aparece em pending no saldo; na data de available_at, migra para available e pode ser sacado.

Contestação

Se o portador contestar a compra, você recebe o evento charge.disputed e, se a contestação for aceita pelo emissor, charge.chargeback — com o valor debitado do seu saldo. Trate esses eventos: são os únicos que revertem uma venda já confirmada.