Changelog da API

​

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

• Links de pagamento
• Contestações (/v2/chargebacks)
• Checkout.js e 3D Secure
• Alterar próxima cobrança na v1 (na v2, next-billing-date já está em produção)
• Dados de teste da análise de fraude

​

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

​

API v2

• 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.

​

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

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

​

Webhooks: campo webhook_version no payload

{
  "type": "charge.canceled",
  "id": "hook_a1b2c3d4e5f6",
  "webhook_version": "v1",
  "data": { ... }
}

​

Novo evento: tax_invoice.issued

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

​

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

• 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.

• 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.

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

• 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

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

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