Changelog

Releases notáveis da API V1, SDKs e dashboard. Mudanças breaking são marcadas explicitamente.

Mudanças notáveis em produção e nas docs. Datas no formato YYYY-MM-DD.

A API minor é pinada via header Zhex-Version: YYYY-MM-DD. Mudanças que afetam contrato (shape de response, comportamento de endpoint) sobem a versão minor; correções internas (segurança, performance) saem direto sem bump.

2026-04-27 — Phase A (atritos da API headless)

Três atritos que faltavam pra integração 100% headless ficaram fechados.

Adicionado

next_action no PaymentIntent — quando o intent fica em requires_action, a response agora carrega next_action Stripe-style com 3 variantes:
- pix_display_qr_code — qr_code_data (BR Code), qr_code_url, expires_at
- boleto_display_details — line_code (47 dígitos IPTE), pdf_url, barcode_url, expires_at
- redirect_to_url — url para 3DS challenge ou redirect bancário
Confirm direto via pm_* em POST /v1/payment_intents/:id/confirm — aceita tanto tok_* (single-use, fresh do zhex.js) quanto pm_* (cartão salvo do customer). Body opcional off_session: true sinaliza recurring billing ao adquirente. Cross-customer ou cross-mode rejeitam com payment_method_not_found (mesma resposta de id inexistente — sem leak).
UI de Origens no dashboard em Developers → Origens. Adiciona/remove domínios autorizados a tokenizar via zhex.js sem precisar de cURL.

Documentação

concepts/tokenization.mdx — fluxo pm_* saved-card removeu o hedge "roadmap"
payments/{cartao,pix,boleto}.mdx — exemplos concretos de next_action.{redirect_to_url,pix_display_qr_code,boleto_display_details}
recipes/one-click-pix.mdx — fluxo "1 clique" agora cobra direto via pm_* salvo
concepts/payment-intents.mdx — tabela canônica dos 3 tipos de next_action

2026-04-27 — Fixes de produção encontrados via smoke real

Smoke contra API local + app teste demonstrável (acme-cursos) descobriu três bugs críticos. Todos fixados e com smoke confirmando o caminho corrigido.

Corrigido

KMS EncryptionContext divergente entre encryptWithCompositeKey (service: 'composite-encryption' + backendKey/storageKey) e decryptWithCompositeKey (service: 'composite-decryption' sem esses fields). AWS KMS exige AAD idêntica — o decrypt teria falhado em produção real com InvalidCiphertextException. Padronizado num único buildCompositeContext() usado por ambos os métodos.
IdempotencyInterceptor não estava registrado no APP_INTERCEPTOR global do HttpModule. Resultado: todo POST/PUT/DELETE silenciosamente ignorava o header Idempotency-Key. Em retry de network o cliente duplicaria cobrança. Smoke confirma agora Idempotent-Replayed: true em retry de mesma key + 422 em conflict (key reutilizada com body diferente).
encryptedExpiry faltando no schema.prisma (mas presente como NOT NULL no banco) quebrava creditCard.create() em todo fluxo de save de cartão. Cadeia inteira corrigida: schema, entity, repos, use cases (process-credit-card, process-payment-method, create-payment-method-from-token). encryptForStorage consolidado para retornar um único blob expiry = KMS.encrypt("MM/YYYY") em vez de duas strings separadas concatenadas (caminho irrecuperável anterior).

2026-04-25 — API V1 publicada

Primeira versão pública da API V1. Equivale ao "Day 0" para devs externos.

Adicionado

Endpoints /v1/* com convenção Stripe-style (snake_case, cursor pagination, POST para update). Recursos: tokens, customers, payment_intents, payment_methods, refunds, products (+ price sub-resource), customer_subscriptions, events, webhook_endpoints, balance.
Test mode first-class com zsk_test_*/zk_test_*/zrk_test_* + MockPaymentAdapter cobrindo cartões 4242 4242 4242 4242 (sucesso), 4000 0000 0000 0002 (decline), 4000 0000 0000 9995 (insufficient), 4000 0000 0000 3220 (3DS), 4000 0000 0000 0259 (chargeback simulado). Cross-mode 404 sem leak.
/v1/test_helpers/payment_intents/:id/{succeed,fail,expire} — força transição de PaymentIntent em test mode, dispara webhook real. Live keys nesses endpoints retornam 403 test_mode_only.
Webhooks robustos — HMAC-SHA256 (Zhex-Signature: t=<unix>,v1=<hex>), retry exponencial até 7 tentativas (5s, 30s, 5m, 1h, 6h, 24h), tolerância anti-replay 5min, dead_letter após 7ª falha. Endpoint POST /v1/webhook_endpoints/:id/deliveries/:eventId/replay para reentregar manual.
Tokenização hosted via zhex.js Elements em js.zhex.io — PAN/CVV nunca tocam o servidor do merchant (PCI-DSS SAQ-A). Origin allowlist em POST /merchant-origins.
Dashboard /developers/api-keys — criar/revogar chaves com mascaramento e secret-only-once.
OpenAPI 3.x servida em /v1/openapi.json + Swagger UI em /v1/docs.

Webhook events disponíveis hoje

* (todos), payment_intent.succeeded, payment_intent.payment_failed, payment_intent.canceled, charge.dispute.created. Outros (customer.*, payment_method.*, customer_subscription.*, refund.*) são roadmap.

SDKs

@zhexio/zhex-js — pacote browser (~10KB). Zhex(zk_*) → .elements() → tok_*. PostMessage protocol com origin pinning.
@zhex/node — pacote server. Zhex(zsk_*) cobrindo customers, paymentIntents, paymentMethods, refunds, tokens + Zhex.webhooks.constructEvent. Auto-retry com idempotency reuse, auto-pagination via async iterator, errors tipados.

Roadmap explícito (não implementado)

Itens marcados como "roadmap" na docs e que ainda não existem na API:

Disputes — submit evidence, won/lost lifecycle. Hoje chargeback é reembolso compulsório, sem janela de resposta.
Payouts — /v1/payouts controller. Withdrawal interno existe; exposição Stripe-shape virá depois.
BalanceTransactions — ledger granular (charges/refunds/payouts/adjustments).
Subscription template via API — POST /v1/products/:id/subscriptions. Hoje configurado pelo dashboard.
Coupon CRUD via API — idem.
Connect / multi-merchant — header Zhex-Account, /v1/accounts, /v1/account_links.
Capture flow — POST /v1/payment_intents/:id/capture, requires_capture status, capture_method: manual.
Customer soft delete + LGPD anonymize.
metadata field universal nas entities.
Apple Pay / Google Pay no Elements.
Boleto regenerate (segunda via).
PIX Automático (BACEN PIX Auto).
Multi-partial refunds (hoje single-shot por PI).
Radar regras customizáveis (smart routing por BIN e circuit breaker já existem internamente).
expand[] query param.
Zhex-Test-Force-Error header.
CLI zhex binary.

Cada item dessa lista vira uma entry própria no changelog quando entrar.

Nesta página