CLI

Casos de Uso

Receitas prontas para o dia a dia — do “gerar um PIX agora” até pipelines de CI com saída JSON.

Cobrança rápida no terminal

hyzepay auth login --api-key $HYZEPAY_API_KEY --base-url https://hyzepay.pro

hyzepay payments create \
  --amount 49.90 \
  --description "Consultoria 1h" \
  --customer-name "Cliente Demo"

# copie o br_code impresso e envie ao pagador

CI / scripts

Em pipelines, prefira env vars + --json + jq:

export HYZEPAY_API_KEY=${{ secrets.HYZEPAY_API_KEY }}
export HYZEPAY_BASE_URL=https://hyzepay.pro

# smoke test
hyzepay health --json | jq -e '.ok == true'

# cria cobrança e extrai checkout_url
CHECKOUT=$(hyzepay payments create \
  --amount-cents 100 \
  --external-id "ci-${GITHUB_RUN_ID}" \
  --description "CI smoke" \
  --json | jq -r '.payment.checkout_url')

echo "Checkout: $CHECKOUT"

Polling de status

Útil quando ainda não há webhook no ambiente:

ID="pedido-1001"
for i in $(seq 1 40); do
  STATUS=$(hyzepay payments get "$ID" --json | jq -r '.payment.status')
  echo "[$i] status=$STATUS"
  case "$STATUS" in
    paid|expired|failed|refunded) break ;;
  esac
  sleep 3
done

Em produção, prefira webhooks payment.paid — polling é fallback, não a fonte da verdade.

Dev com webhooks locais

# 1. receptor + forward para Next.js local
hyzepay webhooks listen \
  --port 4242 \
  --secret "$HYZEPAY_WEBHOOK_SECRET" \
  --forward http://localhost:3000/api/webhooks/hyzepay

# 2. túnel público
cloudflared tunnel --url http://localhost:4242

# 3. cadastre a URL HTTPS no dashboard e use "Enviar teste"

# 4. ou simule localmente
hyzepay webhooks sample payment.paid > /tmp/evt.json
SIG=$(hyzepay webhooks sign --secret "$HYZEPAY_WEBHOOK_SECRET" \
  --body-file /tmp/evt.json --json | jq -r .header)
curl -sS -X POST http://localhost:3000/api/webhooks/hyzepay \
  -H "Content-Type: application/json" \
  -H "X-HyzePay-Signature: $SIG" \
  -H "X-HyzePay-Event: payment.paid" \
  --data-binary @/tmp/evt.json

Idempotência

Sempre envie um external_id estável do seu lado. Retries de rede devolvem o mesmo pagamento:

ORDER_ID="order_42"
hyzepay payments create --amount 99 --external-id "$ORDER_ID" --json
# created: true

hyzepay payments create --amount 99 --external-id "$ORDER_ID" --json
# created: false — mesmo payment.id, sem segundo PIX