Building the Payload

Configuration Choices Before You Build the Payload

Display modes

• displayMode=0 — Modal / iframe (default): payment UI opens in a modal overlay, hosted checkout page is embedded via iframe, customer remains on your site
• displayMode=1 — Redirect: browser navigates to the ZenPay hosted page, customer completes payment externally, ZenPay redirects back to your redirectUrl

Operating modes

• Mode 0 — One-Off Payment: normal one-off payment. Start here for most integrations.
• Mode 1 — Tokenise: capture and store payment details for later reuse without charging immediately.
• Mode 2 — Custom Payment: merchant-defined payment-method toggles and custom payment behaviour.
• Mode 3 — Preauthorisation: place a hold on funds for later capture or void.

Plugin methods

• open() — opens the payment modal. Use when displayMode=0.
• init() — initialises launch behaviour based on displayMode, including redirect. Use this for redirect-based handling.
• close() — closes the modal. Use only for modal / iframe behaviour.

---

Building the Payload

Your backend returns a payload to the frontend. Your frontend should not assemble sensitive values itself.

Required fields: url, merchantCode, apiKey, fingerprint, timestamp, mode, redirectUrl, optional callbackUrl, merchantUniquePaymentId, customerName, customerReference, customerEmail, paymentAmount, displayMode

Treat these as mandatory in all new integrations (even though technically optional for backwards compatibility): customerName, customerEmail, merchantUniquePaymentId. Card issuers are beginning to mandate customerEmail with payments, so treating all three as mandatory now avoids future issues.

const payment = zpPayment({
  url,
  merchantCode,
  apiKey,
  fingerprint,
  timestamp,
  mode: 0,
  redirectUrl,
  callbackUrl,
  merchantUniquePaymentId,
  customerName,
  customerReference,
  customerEmail,
  paymentAmount,
  displayMode: 0,
});

payment.init();

For redirect-based handling, use init() instead of open().

---

Generating the Fingerprint

The fingerprint parameter is a SHA3-512 hash of 7 pipe-separated fields, generated server-side only:

apiKey|username|password|mode|paymentAmount|merchantUniquePaymentId|timestamp

Rules:

• All credentials are case-sensitive
• paymentAmount is sent to the plugin in dollars but hashed in whole cents — multiply by 100 and drop the decimal point, so 150.53 hashes as 15053, 123.1 as 12310 and 123 as 12300. For Mode 2, always hash 0.
• timestamp must be UTC ISO 8601 format: YYYY-MM-DDTHH:mm:ss — no timezone suffix, no milliseconds
• username and password are used only in the hash — they are never sent in the plugin payload
• Each merchantUniquePaymentId + timestamp combination must be unique per attempt

Tools: the Fingerprint Generator and Fingerprint Validator (linked in the Reference page) let you test your implementation.

Timing tip: generate the fingerprint on button press, not page load. It has a 15-minute lifespan based on its timestamp — generating it too early risks E08 or E03 expiry errors if the user waits before clicking Pay, or closes and reopens the modal. Generate it only when the Pay button is pressed, unless the plugin is also displayed at page load.