> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4seletpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog da API

> Histórico de versões, novas funcionalidades e correções da API 4Selet Pay.

Acompanhe as atualizações e o histórico de versões da API.
Este changelog é atualizado continuamente com melhorias, novas funcionalidades e correções relevantes.

## Atualizações Recentes

**8 de Out, 2026**

## Documentação: v2 como padrão, guia de integração e recursos em breve

A API não mudou nesta atualização. Mudou a documentação, para que você integre a v2 de ponta a ponta sem depender de outras fontes.

**v2 como versão padrão.** A documentação abre na **v2**, com uma home própria. A v1 continua disponível no seletor de versão, marcada como **Legado**.

**Novas páginas da v2:**

| Página | O que traz |
| - | - |
| [Guia de integração](https://docs.4seletpay.com.br/pages/v2/start/guia-de-integracao.md) | O passo a passo de cartão, PIX, assinatura, cupons e estorno, e o checklist de produção |
| [Ambiente de Sandbox](https://docs.4seletpay.com.br/pages/v2/start/ambiente-de-sandbox.md) | Endereços, chave `sk_test_` e o que dá para testar sem movimentar dinheiro |
| [Configurar endpoints](https://docs.4seletpay.com.br/pages/v2/webhooks/endpoints.md) | Como cadastrar o webhook com autenticação e reenvio |
| [Entregas e reenvio](https://docs.4seletpay.com.br/pages/v2/webhooks/entregas.md) | Intervalos de reenvio, `GET /v1/webhook-events` e `POST /v1/webhook-events/{code}/resend` |

**Ambiente de Sandbox.** O ambiente de testes passa a se chamar **Ambiente de Sandbox** em toda a documentação. Ele tem endereços próprios, separados da produção, e não há um botão para trocar de ambiente:

| | Produção | Ambiente de Sandbox |
| - | - | - |
| API v2 | `https://app.4seletpay.com.br/api/v2` | `https://sandbox.4seletpay.com.br/api/v2` |
| API v1 | `https://app.4seletpay.com.br/api/v1` | `https://sandbox.4seletpay.com.br/api/v1` |
| Dashboard | `https://app.4seletpay.com.br` | `https://sandbox.4seletpay.com.br` |

**Correção.** O `llms.txt` indicava `https://api.4seletpay.com.br/api/v1` como base da v1. O endereço correto é `https://app.4seletpay.com.br/api/v1`.

**Em breve.** Estes recursos já podem ser testados no Ambiente de Sandbox e ainda não estão em produção, onde as rotas respondem `404`. As páginas estão marcadas com **Em breve**:

* [Links de pagamento](https://docs.4seletpay.com.br/pages/links-de-pagamento/reference.md)
* [Contestações](https://docs.4seletpay.com.br/pages/v2/contestacoes/reference.md) (`/v2/chargebacks`)
* [Checkout.js e 3D Secure](https://docs.4seletpay.com.br/pages/checkout-js/reference.md)
* [Alterar próxima cobrança](https://docs.4seletpay.com.br/pages/assinaturas/next-charge-date.md) na v1 (na v2, `next-billing-date` já está em produção)
* [Dados de teste da análise de fraude](https://docs.4seletpay.com.br/pages/analise-de-fraude/dados-de-teste.md)

**15 de Set, 2026**

## API v2: três rotas de assinatura mudam de verbo

> [!WARNING]
>
> **Mudança incompatível.** Três rotas de assinatura da API v2 deixaram de aceitar `POST`. Chamadas com `POST` nessas rotas passam a receber `405 Method Not Allowed`, fora do envelope de erro da v2. Atualize a sua integração para o verbo novo.

| Rota | Antes | Agora |
| - | - | - |
| `/v2/subscriptions/{id}/payment-method` | `POST` | `PUT` |
| `/v2/subscriptions/{id}/next-billing-date` | `POST` | `PUT` |
| `/v2/subscriptions/{id}/items/{code}` | `POST` | `PATCH` |

O path, o corpo da requisição, as respostas, os códigos de erro e o header `Idempotency-Key` continuam iguais. Só o verbo HTTP mudou.

Em `PATCH /v2/subscriptions/{id}/items/{code}`, a atualização é parcial: `quantity`, `amount` e `description` são opcionais, e é preciso enviar pelo menos um deles.

**14 de Set, 2026**

## API v2

Lançamento da **API v2**: pedidos com vários meios de pagamento, assinaturas, faturas e cartões salvos, com autenticação por chave de API e respostas planas. Selecione a versão **v2** no topo da documentação.

**Novos endpoints:**

| Método | Endpoint | Descrição |
| - | - | - |
| `POST` | `/v2/orders` | Criar pedido com um ou mais pagamentos |
| `GET` | `/v2/orders/{id}` | Consultar pedido |
| `POST` | `/v2/orders/{id}/capture` | Capturar pedido autorizado |
| `POST` | `/v2/orders/{id}/cancel` | Cancelar pedido |
| `POST` | `/v2/orders/{id}/confirm` | Confirmar código de verificação |
| `POST` | `/v2/orders/{id}/confirm/resend` | Reenviar código de verificação |
| `GET` | `/v2/charges/{id}` | Consultar cobrança |
| `POST` | `/v2/charges/{id}/refund` | Estornar cobrança |
| `POST` | `/v2/cards` | Salvar cartão |
| `GET` | `/v2/cards/{id}` | Consultar cartão |
| `POST` | `/v2/subscriptions` | Criar assinatura |
| `GET` | `/v2/subscriptions/{id}` | Consultar assinatura |
| `POST` | `/v2/subscriptions/{id}/cancel` | Cancelar assinatura |
| `POST` | `/v2/subscriptions/{id}/payment-method` | Alterar meio de pagamento |
| `POST` | `/v2/subscriptions/{id}/items/{code}` | Atualizar item |
| `POST` | `/v2/subscriptions/{id}/next-billing-date` | Alterar data da próxima cobrança |
| `GET` | `/v2/subscriptions/{id}/invoices` | Listar faturas |
| `GET` | `/v2/invoices/{id}` | Consultar fatura |
| `POST` | `/v2/invoices/{id}/pay` | Pagar fatura |
| `POST` | `/v2/invoices/{id}/confirm` | Confirmar código de verificação da fatura |
| `POST` | `/v2/invoices/{id}/confirm/resend` | Reenviar código de verificação da fatura |

**Principais mudanças em relação à v1:**

* **Autenticação por chave de API** (`Authorization: Bearer sk_...`), sem header `account`.
* **Valores em centavos** inteiros em todos os campos.
* **Vários pagamentos no mesmo pedido** — dois cartões ou cartão + PIX, com split por pagamento.
* **Erros padronizados** no envelope `{ "error": { "type", "code", "message" } }` e pagamento recusado como `402` com `failure_reason`.
* **Idempotência** com o header `Idempotency-Key`.
* **Webhooks no formato v2** para recursos criados pela v2, identificados por `webhook_version`.

A API v1 continua disponível. Consulte o guia [Migrando da v1](https://docs.4seletpay.com.br/pages/v2/start/migracao-v1.md) para planejar a mudança.

**14 de Ago, 2026**

## Cartões: um único endpoint para salvar e tokenizar

Unificamos o cadastro de cartão em **um só endpoint**. Antes, salvar um cartão para uso posterior exigia duas chamadas — uma para criar o cartão e outra, separada, apenas para tokenizá-lo. Agora **a criação do cartão já dispara a tokenização**, e não existe mais rota de tokenização avulsa.

**Endpoints removidos:**

| Método | Endpoint | Substituído por |
| - | - | - |
| `POST` | `/v1/clients/{clientCode}/cards` | `POST /v1/clients/{clientCode}/cards/tokens` |
| `POST` | `/v1/clients/{clientCode}/cards/{cardId}/tokens` | `POST /v1/clients/{clientCode}/cards/tokens` |

**Endpoint único de cadastro:**

```http theme={null}
POST /v1/clients/{clientCode}/cards/tokens
```

> [!WARNING]
>
> **Mudança incompatível.** Se a sua integração chamava `POST .../cards` seguido de `POST .../cards/{cardId}/tokens`, troque as duas chamadas por uma única chamada a `POST .../cards/tokens` com o mesmo corpo do antigo cadastro. As demais rotas de cartão (listar, consultar, atualizar e excluir) permanecem inalteradas.

O comportamento é o mesmo já documentado: a resposta volta imediatamente com `202 Accepted` e `tokenization_status: "pending"`, e o resultado da tokenização chega por webhook (`card.token_created` / `card.token_failed`). Não é necessário fazer polling.

**`card_token` em toda representação de cartão:**

O campo `card_token` passa a aparecer em **todas** as respostas e eventos de cartão — não apenas no `card.token_created`. Ele é o identificador do cartão salvo e continua sendo o valor enviado em `payment.card.card_token` ao criar uma cobrança.

***

## Webhooks: campo `webhook_version` no payload

Todo webhook desta documentação passa a incluir o campo `webhook_version` no envelope, identificando o formato do payload:

```json theme={null}
{
  "type": "charge.canceled",
  "id": "hook_a1b2c3d4e5f6",
  "webhook_version": "v1",
  "data": { ... }
}
```

O valor é sempre `v1` para os eventos documentados aqui. É uma **adição** ao payload — nenhum campo existente mudou de nome ou de formato. Trate valores desconhecidos de forma tolerante para conviver com formatos futuros.

***

## Novo evento: `tax_invoice.issued`

A emissão de nota fiscal agora notifica sua aplicação. O evento `tax_invoice.issued` é disparado quando **todas** as notas de um pedido são autorizadas, e traz os links públicos dos PDFs prontos para entregar ao cliente.

```json Payload theme={null}
{
  "type": "tax_invoice.issued",
  "id": "hook_a1b2c3d4e5f6",
  "webhook_version": "v1",
  "data": {
    "order_code": "ord_9f3c1b2a",
    "email": "joao@exemplo.com.br",
    "customer_name": "João Silva",
    "corporate_name": "Minha Empresa LTDA",
    "total_amount": "R$ 199,90",
    "invoices": [
      {
        "model": "serviceInvoice",
        "code": "000000123",
        "pdf_url": "https://app.spedy.com.br/public/service-invoices/8f14e45f-ea1c-4f2b-9d61-3f2c7b8a1d05/pdf"
      }
    ],
    "products": "Plano Mensal Premium",
    "payment_method": "Cartão de Crédito"
  }
}
```

Consulte a [referência do evento](https://docs.4seletpay.com.br/pages/webhooks/events/tax-invoice.md) para a descrição completa dos campos.

**16 de Jul, 2026**

## Cartões salvos, tokenização e cobrança com `card_token`

Novo conjunto de rotas para **gerenciar os cartões salvos de um cliente** e reutilizá-los nas cobranças, além de melhorias no `/charge`.

**Novos endpoints — Cartões:**

| Método | Endpoint | Descrição |
| - | - | - |
| `POST` | `/v1/clients/{clientCode}/cards/tokens` | Salvar cartão do cliente (tokenização assíncrona) |
| `GET` | `/v1/clients/{clientCode}/cards` | Listar cartões do cliente |
| `GET` | `/v1/clients/{clientCode}/cards/{cardId}` | Consultar cartão |
| `PUT` | `/v1/clients/{clientCode}/cards/{cardId}` | Atualizar cartão (nome, tipo, bandeira, validade) |
| `DELETE` | `/v1/clients/{clientCode}/cards/{cardId}` | Excluir cartão (soft delete) |

**Cobrança com cartão salvo (`/charge`):**

* Agora é possível enviar `payment.card.card_token` (o token retornado ao salvar o cartão / no evento `card.token_created`) **no lugar dos dados completos do cartão**. Os campos `number`, `name`, `month`, `year` e `security_code` tornam-se opcionais quando `card_token` é enviado (continue enviando `installments`).
* Toda cobrança com cartão passa a retornar o `card_token` em `data.orders[].charges[].payment.card_token` — tanto ao enviar `card_token` quanto os dados completos (nesse caso o cartão é salvo e o `card_token` é devolvido). Em pagamentos sem cartão (ex.: PIX), vem `null`.
* O billing address **não** é tokenizado: ao cobrar com `card_token`, informe o billing address (`client.address`) na requisição.

**Segurança e comportamento:**

* O número completo do cartão (PAN) e o CVV **nunca** são retornados — apenas `first_six_digits` e `last_four_digits`.
* As rotas de cartão e o uso de `card_token` são **escopados por conta** — um `card_token` de outra conta é rejeitado com `422`.
* **Tokenização assíncrona por webhook**: ao salvar um cartão (`POST .../cards/tokens`), a resposta retorna imediatamente com `tokenization_status: "pending"` e o resultado é entregue por webhook. Novos eventos de cartão: `card.created`, `card.updated`, `card.deleted`, `card.expired`, `card.token_pending`, `card.token_created` e `card.token_failed`.
* Exclusão é *soft delete* e é bloqueada (`409`) quando o cartão está vinculado a uma assinatura ativa.

**Exemplo — cobrar com cartão salvo:**

```json Request theme={null}
POST /v1/charge
Authorization: Bearer {token}
account: {accountcode}

{
  "client": {
    "name": "João Silva",
    "email": "joao@exemplo.com.br",
    "phone": { "ddi": "55", "ddd": "11", "number": "999999999" },
    "document": { "type": "CPF", "number": "123.456.789-09" }
  },
  "items": [
    { "id": "produto_001", "description": "Camiseta Premium", "amount": 99.90, "quantity": 1 }
  ],
  "payment": {
    "type": "CreditCard",
    "card": { "card_token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f", "installments": 1 }
  }
}
```

**27 de Mai, 2026**

## Links de Pagamento

Lançamento dos **Links de Pagamento** — um novo recurso que permite criar checkouts pré-configurados e compartilhá-los diretamente com seus clientes, sem precisar construir uma página de pagamento do zero.

Cada link gera uma URL única com token de segurança. O cliente acessa, confirma os dados e paga. Você recebe a notificação via webhook.

**Novos endpoints:**

| Método | Endpoint | Descrição |
| - | - | - |
| `POST` | `/v1/payment-links` | Criar novo link de pagamento |
| `GET` | `/v1/payment-links` | Listar links da conta (paginado) |
| `GET` | `/v1/payment-links/{code}` | Consultar link por código |
| `POST` | `/v1/payment-links/{code}/cancel` | Cancelar link |
| `DELETE` | `/v1/payment-links/{code}` | Excluir link |

**Principais funcionalidades:**

* **Dados do cliente pré-preenchidos** — nome, e-mail, telefone, documento e endereço já chegam preenchidos no checkout
* **Métodos de pagamento configuráveis** — `CreditCard`, `PIX` ou `Boleto`; se omitido, todos os métodos ativos da conta são exibidos
* **Parcelamento por milestones** — defina faixas de parcelas com taxas de juros específicas; o sistema expande automaticamente de 1x a 12x
* **Imagem no checkout** — envie uma URL pública ou string base64; o servidor processa e armazena automaticamente (fail-soft: se falhar, o link é criado sem imagem e a resposta inclui `image_warning`)
* **Desconto exclusivo PIX** — percentual ou valor fixo aplicado apenas para pagamentos via PIX
* **Expiração automática** — defina `expires_at` para desativar o link em uma data futura
* **Limite de usos** — defina `max_uses` para encerrar o link após um número máximo de pagamentos
* **Split de pagamento** — divida o recebimento automaticamente entre múltiplos recebedores por percentual ou valor fixo
* **Privacidade no checkout** — `obfuscate_client` mascara os dados do pagador; `obfuscate_items` oculta itens e valores
* **URLs de navegação** — `back_url` para o botão "Voltar" e `redirect_url` para redirecionar após pagamento confirmado
* **Frete** — valor adicional somado ao total dos itens

**Exemplo — criar link básico:**

```json Request theme={null}
POST /v1/payment-links
Authorization: Bearer {token}
account: {accountcode}

{
  "client": {
    "name": "Hugo Belo",
    "email": "hugo@exemplo.com.br",
    "phone": { "ddi": "55", "ddd": "62", "number": "984063942" }
  },
  "items": [
    {
      "id": "plano-premium",
      "description": "Plano Mensal Premium",
      "amount": 97.99,
      "quantity": 1
    }
  ],
  "config": {
    "payment_types": ["CreditCard", "PIX"],
    "expires_at": "2026-12-31 23:59:59",
    "pix_discount_value": 10,
    "pix_discount_type": "percentage",
    "redirect_url": "https://meusite.com.br/obrigado"
  }
}
```

```json Resposta (HTTP 201) theme={null}
{
  "mensagem": "Link de pagamento criado com sucesso",
  "erro": false,
  "mensagenserro": [],
  "codigoretorno": 201,
  "id": "00000000-0000-0000-0000-000000000000",
  "data": {
    "code": "lnk_abc123xyz",
    "url": "https://checkout.4seletpay.com.br/lnk_abc123xyz?token=...",
    "status": "InProgress",
    "value": 97.99,
    "uses_count": 0,
    "created_at": "2026-05-27T10:00:00.000000Z"
  }
}
```

Consulte a [documentação de Links de Pagamento](https://docs.4seletpay.com.br/pages/links-de-pagamento/reference.md) para detalhes completos de todos os campos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.