Test and go live

Get webhooks on your machine

Hashry sends webhooks only to a public https address. A tunnel gives your machine one. These steps use ngrok. Any tunnel works.

1. Start a tunnel to the server that has the webhook route:

   # Express or Python: the server itself, on port 8000
   ngrok http 8000
   
   # Next.js: the https dev server, on port 3000
   ngrok http https://localhost:3000
   
   # SvelteKit: the https dev server, on port 5173
   ngrok http https://localhost:5173

2. ngrok prints a public address, such as https://abc123.ngrok-free.app. Your webhook URL is that address plus /api/webhooks/hashry.
3. In the Hashry admin, open the Test Sandbox tab. In Test notifications, add your webhook URL. (The admin calls it the notification address.)
4. Choose Rotate test signing secret. Copy the secret (hwhsec_test_…): it is shown once.
5. Put it in HASHRY_WEBHOOK_SECRET, and restart your server.
6. Pay a new test order. The webhook arrives, and your route answers 200. ngrok's page at http://localhost:4040 shows each delivery.

Test cards

Use any expiry date in the future, and 123 as the security code (CVC).

What to try

Use a new order for each case. With the stand-in database, change the test order's ID and restart your server.

• Pay with 4012000000020071. The order turns paid, and a webhook arrives.
• Pay with 4012000000020121, then 4012000000020071 in the same card form. The form says the card was declined and takes the second one. The order turns paid. No payment.failed webhook arrives.
• Decline three cards in a row (…0121, …0089, …0121). The page says every card was declined, and payment.failed arrives. "Try again" brings a new card form.
• Leave the card form open for 10 minutes. A fresh one appears for the same payment.
• Close the tab right after paying. The webhook still marks the order paid.
• Choose "Open the payment page in full", if the card form offers it. You come back through your return route to the pay page.
• Replay a webhook from ngrok's page within 5 minutes. Your route answers 200, and the order changes once.
• Replay a webhook with one byte of the body changed (ngrok: Replay with modifications). Your route answers 400.

Too many declines in a row pauses the card form for a few minutes. See Declines and retries for the limits.

Going live

The merchant sets up the Live tab in the admin. Then check each item:

• A live key is issued. Your server has HASHRY_CLIENT_SECRET=hsk_live_… and HASHRY_ENVIRONMENT=live.
• Your production https address is on the live Allowed return origins and Allowed embed origins. PUBLIC_BASE_URL is that address.
• The live webhook URL is set, and the live signing secret (hwhsec_live_…) is in HASHRY_WEBHOOK_SECRET.
• Revoke keys used from a web browser is on.
• The build guard runs in your production build. Secrets live only in server settings.
• Your real database replaces the stand-in, and the test order is gone.
• Handled webhook event IDs are saved in your database, in the same transaction as the order change.
• Your logs never hold embed_url, tokens or secrets.
• Make one small live payment. Check the order, the webhook, and the payment in the admin.