Conceitos
O modelo mental da Zhex — recursos, ciclos de vida, idempotência, eventos. Sete páginas que cobrem 90% da integração.
A API da Zhex foi modelada como um conjunto de recursos REST com ciclo de vida explícito. Cada recurso tem um conjunto pequeno de estados, transições previsíveis e eventos correspondentes — você nunca faz polling, sempre escuta.
Estas seis páginas são o que separa "fiz funcionar uma vez" de "rodando em produção sem chamados às 2 da manhã":
PaymentIntent
O recurso central. Lifecycle requires_payment_method → succeeded, confirm, cancel, requires_action.
Tokenização
Por que zhex.js Elements coloca você em PCI-DSS SAQ-A. Token vs PaymentMethod.
Test mode
MockAcquirerAdapter, cartões 4242…, isolamento de dados, webhooks de teste.
Webhooks
Verificação HMAC, retry, DLQ, replay, idempotência no consumer.
Customers
Customer + PaymentMethod, document (CPF/CNPJ), endereço.
Assinaturas e billing
Subscription (plano) vs CustomerSubscription (ativa), trial, dunning, lifecycle.
A grande regra
Toda chamada que cria recurso na Zhex (POST /v1/...) tem três coisas em comum:
Authorization: Bearer zsk_*— secret key, server-side only.Idempotency-Key: <uuid>— UUID v4 reutilizado em todos os retries da mesma operação lógica.- Resposta com
idprefixado —pi_*para PaymentIntent,cus_*para Customer,sub_*para Subscription, etc.
Saber esses três trechos faz você dispensar 80% das idas ao Ctrl+F na referência da API.
O fluxo canônico
Quase toda integração de cobrança se resume ao mesmo desenho:
Cada caixa azul é uma seção dessas Conceitos. Comece pela PaymentIntent.
Atualizado em