Developers · Hashry Pay

Troubleshooting

Find what you see, then follow the fix. For the full list of error codes, see Errors.

The card form

What you see	Why, and what to do
The browser says the connection is not private.	Your dev server uses its own certificate. That is safe on your machine: choose to go on. In production, use a real certificate.
The page says "Something went wrong" right away.	Your payment route answered with an error. Open the browser's network tab and find the call to `/payment`. Its answer has an `error` code. Look it up in Errors from your routes.
The card form never appears. After 15 seconds, `onError` gets `load_timeout`.	The card form loads only inside an https page at the origin your server sent as `embed_origin`. Open the page at exactly `PUBLIC_BASE_URL`: the same scheme, host and port. `localhost` and `127.0.0.1` are not the same origin.
The card form says "Too many attempts".	Too many declines in a short time. Wait a few minutes, then use "Try again" in the card form. See Declines and retries.
The page stays on "Your payment is still being processed".	Hashry does not have the outcome yet. The webhook brings it. Reload the page later to check again. Never start a second payment for the order.

When a call to Hashry fails, your routes answer with JSON such as { "error": "origin_not_allowed", "retry": false }. These are the common codes.

error	Why	What to do
`order_not_found`	No order has that ID. The stand-in database forgets orders when the server restarts, apart from test-order.	Open the pay page of an order that exists, such as /orders/test-order/pay.
`embed_origin_not_allowed`	The address of your page is not on Allowed embed origins.	Add it on the admin tab for your key (Test Sandbox or Live). Use the exact origin: https, the host, and the port if it is not 443. No path, no slash at the end.
`origin_not_allowed`	The address of your page is not on Allowed return origins.	Add the same origin there too. Both lists need it.
`embedded_checkout_not_enabled`	The embedded card form is off for this account.	Ask Hashry support to turn it on.
`currency_mismatch`	The order's currency is not the store's currency.	Change JMD in the test order to your store's currency.
`authentication_error`	The client ID or secret is wrong, or the key was revoked.	Check your settings file, then restart the server. Settings are read only at start.
`hashry_unreachable`	Your server got no answer from Hashry.	Check the network, then try again. It is safe: the same idempotency key is sent.

What you see	Why, and what to do
"Set PUBLIC_BASE_URL to your https origin."	The setting is missing, or does not start with `https://`. Add it to your settings file.
`ConfigurationError`	The key and `HASHRY_ENVIRONMENT` don't match. A test key (`hsk_test_…`) needs `sandbox`. A live key needs `live`.
Python: `KeyError: 'HASHRY_CLIENT_ID'`	The settings were not loaded. Start uvicorn with `--env-file .env`, from the folder that holds `.env`.

What you see	Why, and what to do
No webhooks arrive.	Check the webhook URL in the admin. It must be public and https, and end in `/api/webhooks/hashry`. If you use a tunnel, its address may have changed. See Get webhooks on your machine.
Your webhook route answers 400.	A check failed. The `error` in the answer says which one. The usual causes: `HASHRY_WEBHOOK_SECRET` is wrong (a test secret with live, or an old secret); the body was parsed before the check (in Express, `express.json()` ran first); a proxy changed the path; or the server clock is more than 5 minutes off.
Your webhook route answers 5xx.	It could not read the payment from Hashry. Hashry sends the event again later, so nothing is lost.

What you see	Why, and what to do
The build fails with `secret-key`, `server-sdk` or `secret-env-name`.	The build guard found a secret, or Hashry server code, in browser code. Move it to your server. If it was a real secret, rotate the key. See Build guard.
Next.js: the build guard never runs.	The build used Turbopack. Keep `--webpack` in your `dev` and `build` scripts.
Next.js: an error about `server-only`.	A client component imports `lib/hashry.ts`. Call your own routes from the page instead.