PaymentIntent

PaymentIntent é o recurso central da Zhex. Ele representa uma intenção de cobrar e percorre uma máquina de estados explícita até succeeded ou canceled.

A diferença entre PaymentIntent e modelos antigos de "Charge": cada PaymentIntent é uma jornada inteira com retentativas e múltiplos métodos de pagamento sob o mesmo id. Você cria uma vez, acompanha por status, e não precisa lidar com IDs intermediários.

Lifecycle

Cada transição emite um evento webhook. Não faça polling — escute via webhook e use a API só para confirmar o estado atual em rotas de retry.

Criar PaymentIntent

curl https://prometheus.zhex.io/v1/payment_intents \
  -H "Authorization: Bearer $ZHEX_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Zhex-Version: 2026-04-25" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49700,
    "currency": "brl",
    "customer": "cus_…",
    "payment_method_types": ["pix", "card", "boleto"],
    "description": "Curso Node Avançado · Acesso 12m"
  }'

Campos aceitos

Atribuição (UTM tracking)

Para correlacionar tráfego pago com receita sem montar pipeline próprio, mande os parâmetros de atribuição no payload do PaymentIntent. Vale para qualquer método — cartão, PIX, boleto. A Zhex armazena junto com a transação e, no confirm, dispara o webhook de integração (Utmify, etc.) com o payload enriquecido.

const intent = await zhex.paymentIntents.create({
  amount: 49700,
  currency: 'brl',
  customer: 'cus_…',
  payment_method_types: ['card'],
  utm: {
    utm_source: 'facebook',
    utm_medium: 'cpc',
    utm_campaign: 'black_friday_2026',
    utm_content: 'video_ad_v3',
    utm_term: 'curso node',
    utm_referrer: 'https://www.facebook.com/...',
    utm_landing_page: 'https://meusite.com/?utm_source=facebook&...',
    src: 'aff_marketing_pro',  // afiliado / partner — opcional
    sck: 'sub_001',             // sub-campanha do afiliado — opcional
  },
});

Campos aceitos no utm — todos opcionais, mande só o que tem:

Resposta

{
  "id": "pi_3MtwBwLkdIwHu7ix28a3tqPa",
  "object": "payment_intent",
  "livemode": false,
  "amount": 49700,
  "currency": "brl",
  "status": "requires_payment_method",
  "customer": "cus_…",
  "description": "Curso Node Avançado · Acesso 12m",
  "payment_method_types": ["pix", "card", "boleto"],
  "last_payment_error": null,
  "charges": { "latest": null },
  "next_action": null,
  "utm": {
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "utm_campaign": "black_friday_2026",
    "utm_term": null,
    "utm_content": null,
    "utm_referrer": null,
    "utm_landing_page": null,
    "src": null,
    "sck": null
  },
  "created": 1714057200
}

charges.latest recebe o ID do charge na adquirente quando a confirmação roda. last_payment_error é populado em canceled quando a transação falhou (com code e message).

utm vem populado em retrieve, confirm e cancel quando o create incluiu atribuição. Em list é sempre null — buscar UTM por intent na lista geraria N+1, então pra ler atribuição em massa use o dashboard ou query direta no BD via export. Quando precisar de UTM por intent específico, faz GET /v1/payment_intents/:id.

Confirmar (anexar token)

Toda confirmação consome um tok_* produzido pelo zhex.js (cartão) ou é gerada server-side em fluxos PIX/boleto. Hoje a API V1 expõe o caminho card → token:

const confirmed = await zhex.paymentIntents.confirm(intent.id, {
  payment_method: 'tok_…',  // do zhex.js
});
// confirmed.status pode ser: succeeded | requires_action | processing | canceled

A resposta traz o status atualizado. Os mais comuns após confirm:

• succeeded — fim feliz, sem 3DS, cartão aprovado direto.
• requires_action — precisa do cliente (3DS challenge, QR PIX, boleto baixar PDF). Para cartão, o 3DS é orquestrado pela própria Zhex; o estado terminal chega via webhook.
• processing — assíncrono (boleto/PIX): cliente já viu o que precisa, esperando pagamento.
• canceled — método foi recusado terminantemente, peça outro (gere novo tok_*).

Quando o intent fica em requires_action, o body traz next_action com o que o cliente precisa fazer:

Veja exemplos completos por método em PIX, Boleto e Cartão.

Cancel

const canceled = await zhex.paymentIntents.cancel(intent.id, {
  cancellation_reason: 'requested_by_customer',
});

cancellation_reason (opcional, livre) vai no audit trail e no webhook.

Você só pode cancelar em requires_payment_method, requires_confirmation ou requires_action. Em processing o cancelamento depende do método (PIX/boleto não confirmado expira sozinho). Em succeeded, use refund.

Retrieve e list

// retrieve
const intent = await zhex.paymentIntents.retrieve('pi_…');

// list (cursor-based)
for await (const intent of zhex.paymentIntents.list({
  customer: 'cus_…',
  limit: 100,
}).autoPagingEach()) {
  /* ... */
}

Use auto-paginação para iterar páginas inteiras com for await.

Webhooks emitidos

Os events que a API hoje dispara para PaymentIntent:

Sempre escute payment_intent.succeeded como fonte da verdade — não confie no body do POST /v1/payment_intents/:id/confirm que parecia succeeded. Network pode mentir, webhook não.

Veja Webhooks para o handler canônico com verificação HMAC.

Idempotência sem armadilha

Use a mesma Idempotency-Key em todas as tentativas da mesma operação lógica. Em billing recorrente, o padrão mensalidade-{customer}-{cycle} é robusto:

await zhex.paymentIntents.create(
  { amount: 9700, currency: 'brl', customer: 'cus_…' },
  { idempotencyKey: `mensalidade:${customerId}:2026-04` },
);

Se o worker rodar duas vezes (deploy, reschedule), a Zhex devolve a mesma resposta cacheada dentro de 24h. Se o body mudar com a mesma key, recebe 422 idempotency_key_in_use.

Erros comuns

Toda resposta de erro tem o shape:

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Sua cobrança foi recusada.",
    "request_id": "req_xyz"
  }
}

request_id é o que você manda pro suporte se algo estiver bizarro.

Próximos passos