Guides

Poll for payment completion

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

Production should always prefer webhooks — they are pushed within milliseconds of the payment landing on-chain or via Lightning. Polling adds latency and rate-budget pressure.

Terminal statuses (completed, expired, failed) should stop the loop. Set a hard timeout so a hung loop doesn't run forever.

A 3-second interval is sensible for an open checkout tab; faster for short-lived Lightning invoices is OK.

Example

# Quick-and-dirty bash loop
REQ=pay_abc123…
while true; do
  STATUS=$(curl -s "https://api.trevi.cash/pay/$REQ" | jq -r '.payment.status')
  echo "status=$STATUS"
  case "$STATUS" in
    completed|expired|failed) exit 0 ;;
  esac
  sleep 3
done

Was this page helpful?

Receive webhooks

Payment statuses