Guides

Poll for payment completion

When webhooks aren't an option (local dev, environments with no public URL), poll the payment endpoint until it reaches a terminal state.

Production should prefer webhooks. Trevi detects settlement either from a wallet notification or by asking the wallet directly, so the callback usually lands within seconds. Polling adds latency and rate-budget pressure.

Terminal statuses are paid, expired, and failed — stop the loop on any of them. Set a hard timeout so a hung loop cannot run forever.

Invoices Trevi requests are payable for 15 minutes, so a 3-second interval on an open checkout tab is sensible and a ceiling around 20 minutes is plenty.

Unlike v1, reading a payment requires authentication — payment_id is not a public handle. Poll from your server, not from the customer's browser.

Example

# Quick-and-dirty bash loop
PAYMENT_ID=pay_abc123…
while true; do
  STATUS=$(curl -s "https://api.trevi.cash/api/v2/payments/$PAYMENT_ID" \
    --header "X-API-Key: $TREVI_API_KEY" | jq -r '.payment.status')
  echo "status=$STATUS"
  case "$STATUS" in
    paid|expired|failed) exit 0 ;;
  esac
  sleep 3
done

Was this page helpful?

Receive webhooks

Payment statuses