---
title: "Troubleshooting"
description: "Diagnose setup, API, checkout, credit, and webhook failures quickly."
canonical_url: "https://checkout.verify.et/docs/troubleshooting"
markdown_url: "https://checkout.verify.et/docs/troubleshooting.md"
last_updated: "2026-10-06"
x_farming_labs_generated_preamble: true
---

# Troubleshooting
URL: /docs/troubleshooting
LLM index: /llms.txt
Description: Diagnose setup, API, checkout, credit, and webhook failures quickly.
Related: /docs/authentication, /docs/webhooks, /docs/api

# Fix common integration failures

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `401` or invalid API key | Missing, malformed, revoked, or incorrect `vchk_…` secret | Replace the server secret from Developer settings; never send the fingerprint. |
| `403` or insufficient scope | The key is valid but lacks the operation's scope | Create or rotate to a least-privilege key with the required deposit permission. |
| Return URL rejected | Its origin is missing, inactive, or does not match scheme/host/port | Register and activate the exact origin; use HTTP only on loopback. |
| No payment options | No active receiving account matches the request | Add or enable an account, or remove an overly restrictive `payment_method`. |
| `402` or insufficient credits | The workspace has no verification credits | Add credits in the dashboard, then retry the same logical operation safely. |
| Checkout says expired | More than 60 minutes elapsed | Create a new deposit and redirect to its new `checkout_url`. |
| Webhook signature fails | Parsed body, wrong secret, stale timestamp, or incorrect `v1` format | Verify the raw bytes against `<timestamp>.<raw-body>` using the endpoint's `whsec_…` secret. |
| Repeated deliveries | The receiver returned non-`2xx`, timed out, or received at-least-once duplicates | Acknowledge after durable storage and deduplicate by event ID. |
| Event appears out of order | Retries and independent deliveries crossed | Retrieve the current deposit and apply only valid state transitions. |

## Before contacting support

Capture the endpoint, HTTP method, status, UTC time, deposit ID when available, and
`meta.requestId` from the response. For webhooks, include event ID and delivery ID.
Redact API keys, signing secrets, authorization headers, customer data, and full
payment references.

<Callout type="warning" title="Do not solve failures by exposing credentials">
  Support never needs the full `vchk_…` API key or `whsec_…` signing secret. Rotate
  a credential immediately if it was pasted into logs, tickets, source control, or chat.
</Callout>

For exact request and response schemas, use the generated [API reference](/docs/api).

## Sitemap

Sitemap discovery is not enabled for this deployment.