PIX

PIX tem menor custo, melhor aprovação e liquidação em segundos no Brasil. É o default recomendado para qualquer cobrança em BRL.

Criar cobrança

curl https://prometheus.zhex.io/v1/payment_intents \
  -H "Authorization: Bearer $ZHEX_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4990,
    "currency": "brl",
    "customer": "cus_…",
    "payment_method_types": ["pix"],
    "description": "Pedido #4821"
  }'

O PaymentIntent é criado em requires_payment_method. Quando você confirma (ou usa o checkout hosted), a Zhex gera o QR PIX e o intent volta em requires_action com next_action:

{
  "id": "pi_…",
  "status": "requires_action",
  "next_action": {
    "type": "pix_display_qr_code",
    "pix_display_qr_code": {
      "qr_code_data": "00020126360014BR.GOV.BCB.PIX0114+5511...",
      "qr_code_url": "data:image/png;base64,iVBORw0KGgo...",
      "expires_at": 1714060800
    }
  }
}

• qr_code_data — BR Code (string) para copy-paste ou gerar QR no seu front.
• qr_code_url — PNG embutido (data URL) ou hosted, quando o adquirente fornece. Use qr_code_data como fonte primária.
• expires_at — Unix timestamp; default 30min, configurável por adquirente.

Lifecycle

Use o webhook payment_intent.succeeded — não faça polling. Liquidação real (banco da Zhex → seu payout) acontece em D+0, não bloqueante para emitir produto.

Refund

const refund = await zhex.refunds.create({
  payment_intent: 'pi_3MtwBwLkdI',
  // omita amount para refund total
  reason: 'requested_by_customer',
});

Refund de PIX liquida em até 1h (BACEN MED) — muito mais rápido que cartão (D+30). Janela máxima: 90 dias após a cobrança.

Hoje cada PaymentIntent aceita um único refund (total ou parcial em valor único). Múltiplos refunds parciais sequenciais são roadmap.

Test mode

Em zsk_test_*, qualquer PaymentIntent PIX pode ser transitado manualmente para succeeded via test helper:

await fetch(
  `https://prometheus.zhex.io/v1/test_helpers/payment_intents/${intent.id}/succeed`,
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.ZHEX_TEST_KEY}` },
  },
);
// dispara webhook payment_intent.succeeded com livemode: false

fail e expire cobrem os outros caminhos. Veja Test mode.

Boas práticas

• Webhook obrigatório. Polling é antipattern: aumenta custo de API e atrasa liberação.
• Idempotency-Key sempre. PIX one-shot retentado sem idempotência duplica intent + duplica QR para o cliente.
• Não regenere PIX ao retomar checkout: crie um PaymentIntent novo. PIX antigo expira sozinho.
• description clara — aparece no extrato do cliente no app do banco.