Changelog da API - 4SeletPay

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

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:

POST /v1/clients/{clientCode}/cards/tokens

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:

{
  "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.

Payload

{
  "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 para a descrição completa dos campos.

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:

Request

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 }
  }
}

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:

Request

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"
  }
}

Resposta (HTTP 201)

{
  "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 para detalhes completos de todos os campos.

​Atualizações Recentes

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

​Webhooks: campo webhook_version no payload

​Novo evento: tax_invoice.issued

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

​Links de Pagamento

Atualizações Recentes

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

Webhooks: campo `webhook_version` no payload

Novo evento: `tax_invoice.issued`

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

Links de Pagamento