ZEN.COM

What you need

my.zen.com → pick your shop → Store settings → Terminal → select the terminal. Three values:

• merchant_uuid: the Terminal UUID
• secret_key: the Paywall secret (the checkout request signature is computed with it)
• webhook_secret: the IPN secret (the hash of ZEN's notification is verified with it)

In your panel choose Settings → Payments → Add method → ZEN.COM and enter all three.

Test environment: ZEN's test account is a separate environment (secure.zen-test.com). Enter the values of your test terminal and tick sandbox (test) mode; going live, enter the live terminal's values and untick the box.

Notification (IPN) URL

The panel attaches its own notification URL to every payment request as customIpnUrl, so ZEN notifies that address for that payment. The URL:

https://<your-panel-domain>/payments/zen/callback

We still recommend pasting the same URL into my.zen.com under Store settings → Terminal → IPN URL: if customIpnUrl were empty, ZEN would use the address stored there. IPN must stay enabled on the terminal, balance is credited by this notification only.

The return URLs (urlSuccess / urlFailure) are attached to every request too; nothing else is configured on ZEN's side.

Flow

1. The customer enters an amount and picks ZEN.COM. No phone is required.
2. The panel sends a signed request to ZEN (terminalUuid, amount, currency, our payment reference as merchantTransactionId, the customer's name and e-mail, one "balance top-up" line item). ZEN returns a redirectUrl and the customer is sent to ZEN's payment page; card entry and 3D Secure happen there.
3. When the payment finishes, the customer's browser comes back to the panel ("Add funds" page). That return credits nothing.
4. ZEN's server POSTs a JSON IPN to the notification URL. The panel recomputes hash with the IPN secret (sha256(merchantTransactionId + currency + amount + status + IPN secret)); a notification that does not match is rejected.
5. If the verified notification says ACCEPTED, the balance is credited. The panel answers {"status":"ok"}; without that answer ZEN resends the same notification for up to a day.

A second notification for the same transaction and the same status is ignored; balance is never credited twice. An ACCEPTED that follows a PENDING is processed as a separate event.

The customer's name sent to ZEN is derived from the username and folded to ASCII ("Şükrü" → "Sukru") so that the case-folding in the signature cannot disagree. Address fields are optional on ZEN's side and are not sent.

Statuses

ZEN status	In the panel
ACCEPTED	completed, balance credited
REJECTED, CANCELED	failed
AUTHORIZED	pending (card authorised, not captured); completes when ZEN sends ACCEPTED, or from Admin → Payments
NEW, PENDING	pending, waiting for the next notification

Notifications of a type other than TRT_PURCHASE (refunds etc.) are verified and acknowledged but never change balance.

Currencies

ZEN's directly supported currencies: EUR, GBP, PLN, USD, AED, AUD, CAD, CHF, CNY, CZK, DKK, HKD, HUF, ILS, JPY, KES, MXN, NOK, NZD, QAR, RON, SAR, SEK, SGD, THB, TRY, UGX, ZAR. Your panel's currency must be one of these; a payment in any other currency is not started. The amount is always sent with two decimals. Which currencies and payment methods are actually enabled on your terminal depends on your ZEN agreement.

Common problems

• Payment page does not open, "ZEN: …" error: wrong Paywall secret or Terminal UUID, or test/live mixed up. The message is the text ZEN returned.
• A second attempt for the same payment is refused: ZEN rejects a second request with the same merchantTransactionId. Start a new payment.
• ACCEPTED in ZEN but no balance: with a wrong IPN secret the notification is rejected as "invalid signature"; the IPN secret in my.zen.com and the panel's webhook_secret must match. Make sure the notification URL is publicly reachable over HTTPS (a domain whose DNS is not yet moved cannot receive it).
• Payment stuck in pending: ZEN has not sent a final status yet (some local methods confirm late) or the status is AUTHORIZED. Check the memo under Admin → Payments.