Troubleshooting

First event is not appearing

• Confirm the server is using the secret key from the environment you are viewing.
• Check that TXNSHIELD_API_BASE_URL points to the control-plane host.
• Look for HTTP 401 or 403 errors in server logs.
• Verify that the protected code path actually executed.

Publishable and secret keys are confused

Publishable keys identify environment context for client-visible use. Secret keys authenticate server-side event ingestion. If a secret key appears in client code, revoke it and create a replacement.

Policy is not taking effect

• Confirm the policy version is published.
• Confirm the protected operation is assigned to the expected policy in the same environment.
• Check whether your app is sending the expected operation key.
• Compare development, staging, and production environment ids.

Transactions are denied unexpectedly

Open the decision log and inspect reasons, score, actor roles, resource, and request summary. Most unexpected denies come from missing roles, a new-device signal, a high requested count, or a stricter policy version than expected.

Step-up does not complete

Make sure the app stops the protected action when step_up_required is returned and only continues after the challenge result is recorded in the next evaluation context.

Webhook signature issues

• Use the endpoint signing secret shown when the webhook is created.
• Validate the raw request body, not a reserialized JSON object.
• Reject requests when the txnshield-signature header is missing or invalid.

Billing state has not updated yet

Stripe checkout and portal changes are synchronized by webhooks. Confirm STRIPE_WEBHOOK_SECRET is configured, check the Billing page event log, and retry the Stripe webhook event if needed.