Testing HelcimPay in Localhost environments

By default, the HelcimPay.js render function does not support localhost environments. If you attempt to call appendHelcimPayIframe() from a local environment, the modal may fail to load or return a security error in the browser console. This limitation ensures that the communication between your frontend and Helcim secure servers occurs over a valid, encrypted tunnel.

Recommended Approach: Using a Tunneling Service

To test HelcimPay.js while developing locally, we recommend using a tunneling service like ngrok. These services provide a temporary, secure public URL (e.g., https://your-session.ngrok-free.app) that "tunnels" traffic directly to your local web server.

Step 1: Set up your tunnel

1. Install a tool like ngrok or Cloudflare Tunnel.
2. Expose your local development port (e.g., port 3000)
3. Copy the secure https URL provided by the service.

Step 2: Initialize your checkout session

Initialize your HelcimPay.js checkout session.

Step 3: Render the modal

Access your local site via the public tunnel URL in your browser. Because the request now originates from a secure public domain, appendHelcimPayIframe(checkoutToken) will function exactly as it does in a production environment.

Testing Checklist

• HTTPS Required: Even in testing, HelcimPay.js requires an HTTPS connection. Tunneling services provide this automatically.
• Token Expiry: Remember that the checkoutToken is unique to each session and expires after 60 minutes or after being consumed by an approved payment.
• Event Listeners: Your window.addEventListener('message', ...) logic will work seamlessly over the tunnel, allowing you to capture SUCCESS or ABORTED events as if you were live.

📘

Developer Test Accounts: We strongly recommend using a Developer Test Account for all localhost testing to avoid processing real transactions while you are configuring your integration.