# 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_

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

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

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

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

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

```bash
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](https://novexfinance.com.br/docs/convencoes#paginacao).


---

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