Referência da API

API REST v1 da Zhex — convenções, headers, autenticação, recursos, paginação, errors e rate limits.

A API da Zhex é organizada por recursos REST, retorna sempre JSON UTF-8, usa HTTP status codes previsíveis e segue versionação dupla:

Major na URL: /v1/... muda só em quebras radicais (raro).
Minor por data via header: Zhex-Version: 2026-04-25 — pinada por chave de API. Mudanças não-breaking saem em datas novas.

Base URL: https://prometheus.zhex.io

Tipo	Endpoints permitidos	Observação
`zk_*` (publishable)	`POST /v1/tokens`	Apenas no front, com origin verificado
`zsk_*` (secret)	Todos	Apenas no servidor
`zrk_*` (restricted)	Conforme `scopes`	Use sempre que o escopo for parcial

Headers

Header	Quando	Notas
`Authorization`	Sempre	`Bearer zsk_*`
`Idempotency-Key`	POSTs financeiros	UUIDv4. Janela 24h.
`Zhex-Version`	Recomendado	`2026-04-25` (formato data ISO)
`Zhex-Parent-Origin`	Iframe `js.zhex.io`	Asserção do origin pai pinado pelo iframe (uso interno)
`Content-Type`	POST	`application/json`

Headers de resposta úteis:

Header	Significado
`Request-Id`	ID único da requisição (cite em suporte).
`Zhex-Should-Retry`	`true` quando você pode retentar com mesma `Idempotency-Key`.
`Idempotent-Replayed`	`true` quando a Zhex devolveu cache da chave (operação só executou 1×).
`Ratelimit-Remaining`	Quantas req restam na janela atual.
`Ratelimit-Reset`	Unix timestamp do reset.

Test mode vs Live mode

Cada par de chaves opera em espaço isolado:

*_test_* → MockAcquirerAdapter. Cartões de teste documentados (4242 4242 4242 4242 = success, 4000 0000 0000 0002 = decline, 4000 0000 0000 3220 = 3DS).
*_live_* → adquirentes reais. Movem dinheiro.

Recursos criados em test mode são marcados com livemode: false e não aparecem em listagens live. Não é possível misturar — chamar /v1/payment_intents/:id com zsk_live_* num ID criado em test retorna 404.

Veja Test mode para a lista completa de cartões e o uso de /v1/test_helpers/... para forçar transições.

Recursos

Tokenização

Recurso	Endpoints
`Token`	`POST /v1/tokens` (aceita `zk_` com Origin allowlistada, `zsk_`, `zrk_*`) — single-use, expira em 15min

Pagamentos

Recurso	Endpoints
`PaymentIntent`	`POST /v1/payment_intents` · `GET /v1/payment_intents/:id` · `GET /v1/payment_intents` · `POST /v1/payment_intents/:id/confirm` · `POST /v1/payment_intents/:id/cancel`
`PaymentMethod`	`POST /v1/payment_methods` (a partir de `tok_*`) · `GET /v1/payment_methods?customer=cus_…` (`customer` obrigatório) · `GET /v1/payment_methods/:id` · `POST /v1/payment_methods/:id/detach`
`Refund`	`POST /v1/refunds` · `GET /v1/refunds/:id` · `GET /v1/refunds?payment_intent=pi_*`

Test helpers (test mode only)

Recurso	Endpoints
Simulação de PaymentIntent	`POST /v1/test_helpers/payment_intents/:id/succeed` · `POST /v1/test_helpers/payment_intents/:id/fail` · `POST /v1/test_helpers/payment_intents/:id/expire`

Live keys nesses endpoints retornam 403 com code: test_mode_only.

Cliente e catálogo

Recurso	Endpoints
`Customer`	`POST /v1/customers` · `GET /v1/customers/:id` · `POST /v1/customers/:id` · `GET /v1/customers?email=…`
`Product`	`POST /v1/products` · `GET /v1/products/:id` · `POST /v1/products/:id` · `GET /v1/products?status=ACTIVE`
`ProductPrice`	`GET /v1/products/:productId/price` · `POST /v1/products/:productId/price`
`CustomerSubscription`	`GET /v1/customer_subscriptions/:id` · `GET /v1/customer_subscriptions` · `POST /v1/customer_subscriptions/:id/cancel`

A CustomerSubscription é a instância ativa de uma assinatura — criada como side-effect de uma PaymentIntent confirmada num produto recorrente. O template do plano (intervalo, ciclo, trial) vive no recurso interno Subscription e é gerenciado pelo dashboard.

Eventos e webhooks

Recurso	Endpoints
`Event`	`GET /v1/events/:id` · `GET /v1/events?type=payment_intent.succeeded`
`WebhookEndpoint`	`POST /v1/webhook_endpoints` · `GET` · `GET /:id` · `POST /:id` (update) · `DELETE /:id` · `POST /:id/rotate_secret` · `POST /:id/deliveries/:eventId/replay`

Saldo

Recurso	Endpoints
`Balance`	`GET /v1/balance` (singleton — sem `:id`, sem list)

Outras superfícies

Disputas (chargebacks), payouts e ledger granular de transações de saldo são gerenciados hoje pelo dashboard da Zhex, não pela API pública. Quando expusermos via API, vão entrar como recursos novos sob /v1/....

Paginação

Cursor-based, não offset. Use starting_after (ID do último item recebido), ending_before e limit (1–100, default 10).

curl "https://prometheus.zhex.io/v1/payment_intents?limit=20&starting_after=pi_3MtwBwLkdI" \
  -H "Authorization: Bearer $ZHEX_SECRET_KEY"

Resposta:

{
  "object": "list",
  "data": [...],
  "has_more": true,
  "url": "/v1/payment_intents"
}

Itere até has_more: false. Veja Auto-paginação para o padrão Node (SDK e helper).

Filtros nativos por recurso

Cada list endpoint aceita filtros adicionais além dos cursores:

Recurso	Filtros
`/v1/customers`	`email`
`/v1/payment_intents`	`customer`
`/v1/refunds`	`payment_intent`
`/v1/payment_methods`	`customer` (obrigatório), `type`
`/v1/products`	`status`
`/v1/customer_subscriptions`	`customer`, `status`
`/v1/events`	`type`
`/v1/webhook_endpoints`	—

Errors

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required param: amount.",
    "request_id": "req_5LJsX2"
  }
}

Tipos

`type`	HTTP	Significado
`invalid_request_error`	400	Payload mal formado, parâmetro faltando/inválido
`authentication_error`	401	Chave inválida, expirada ou ausente
`permission_error`	403	Chave válida mas sem escopo (restricted), ou test/live mismatch
`not_found_error`	404	Recurso não existe nesse modo (test/live)
`idempotency_error`	422	Mesma `Idempotency-Key` com body diferente
`rate_limit_error`	429	Capacidade excedida
`card_error`	402	Cartão recusado, fundos insuficientes, 3DS falhou
`api_error`	5xx	Erro do nosso lado. Você pode retentar com mesma `Idempotency-Key`.

Códigos importantes

`code`	Quando	Ação
`card_declined`	Cartão recusado pelo emissor	Pedir outro cartão
`insufficient_funds`	Sem saldo	Permita trocar de método
`expired_card`	Cartão vencido	Pedir atualização
`incorrect_cvc`	CVV errado	Re-prompt
`processing_error`	Erro temporário do adquirente	Retry com mesma idempotency key
`payment_intent_not_found`	ID não existe nesse modo	Confirme `livemode` da chave
`customer_not_found`	Customer não existe nesse modo	Idem
`token_unusable`	Token expirou, foi consumido ou é de outra partição	Re-tokenizar via `zhex.js`
`unsupported_token_type`	Token de wallet (Apple/Google Pay) onde só `card` é aceito	Roadmap
`origin_not_allowed`	`zk_*` sem origem registrada na allowlist	Cadastrar via `POST /merchant-origins`
`test_mode_only`	`/v1/test_helpers/...` chamado com chave live	Use `zsk_test_*`
`idempotency_key_in_use`	Mesma key, body diferente	Use uma nova chave

Rate limits

Endpoint	Limite
`POST /v1/tokens` (com `zk_*`)	60 req/min por API key
Demais endpoints `/v1/*`	500 req/min por API key

Quando atingido, retorna 429 rate_limit_error com Retry-After em segundos. O SDK @zhex/node respeita automaticamente.

Endpoints públicos (POST /v1/tokens com zk_*) também são protegidos por allowlist de origens — sem o domínio registrado, retorna 403 antes mesmo do rate limit ser avaliado.

Convenções

IDs são stable strings: pi_*, cus_*, prd_*, ppr_*, pm_*, tok_*, re_*, csub_*, evt_*, we_*, wd_*. Sempre tratáveis como opacas.
Timestamps são Unix em segundos (created, expires_at em recursos públicos), exceto no Token (expiresAt/createdAt em ISO 8601 — convenção camelCase do recurso).
Valores monetários em centavos (int). Nunca decimal.
Booleans são true/false literais, não 0/1.
Recursos públicos usam snake_case (exp_month, payment_method, last_payment_error). Único recurso em camelCase é o Token (convenção da camada de tokenização).

OpenAPI Spec

Spec completa em prometheus.zhex.io/v1/openapi.json e Swagger UI navegável em prometheus.zhex.io/v1/docs — importável em Postman, Insomnia, Bruno, ou para gerar client em qualquer linguagem.

Próximos passos

Integração

@zhex/node ou fetch nativo

Conceitos

PaymentIntent, Token, Webhook, Test mode

Recipes

SaaS, Direct Response, e-commerce

Segurança

Idempotência, webhooks, PCI, GA checklist

Esta página foi útil?

Autenticação