# 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](#hospedado) — 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](#direto) — 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_

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

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

```js
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);
```

```python
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_

```json
{
  "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](https://novexfinance.com.br/docs/checkout).

> 🚫 **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_

```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": "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_

```json
{
  "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_

```json
{
  "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](https://novexfinance.com.br/docs/saldo-e-saques); 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.


---

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