DOCSEARCHbyAlgolia
Submit Docs

Zenith Payments Developer Documentation

website·Indexed 30 days ago

https://docs.zenithpayments.support

Developer guides and API references for Zenith Payments (ZenPay), covering integration paths such as Hosted Checkout and Batch Payments. Includes OpenAPI specifications for REST APIs, security best practices regarding rate limiting and credential management, architectural overviews for Payment Links, and release notes up to version 1.130.

Tokens
29.5K
Snippets
97
Records
202
Agent score
50%

What's inside Zenith Payments

  1. Overview of ZenPay Hosted Checkout

    Hosted Checkout is an integrated payment solution where the merchant's frontend initializes a JavaScript plugin (zpPayment(...)) using bootstrap data provided by the merchant's backend. The payment UI is hosted by ZenPay and can be launched as a modal iframe or a full-page redirect.

    Key Responsibilities:

    • Frontend: Requests bootstrap data, initializes the plugin, launches the flow, and handles the return-page UX.
    • Backend: Securely stores credentials, generates the security fingerprint, creates unique payment IDs, and validates server-to-server callbacks.

    When to use: Use Hosted Checkout when you want ZenPay to handle sensitive payment data and host the UI, while keeping your backend as the source of truth for payment state.

  2. Use Sessions to securely launch Zenith Payments Hosted Checkout

    Sessions allow a backend to create secure, short-lived launch data for Hosted Checkout. This architecture ensures that Merchant API credentials remain on the backend and are not exposed to the frontend. Use Sessions whenever the frontend is responsible for launching the Hosted Checkout UI. If the integration is purely backend-led and does not launch a browser-based checkout, Sessions are not required.

  3. Choose a ZenPay integration path

    ZenPay offers three ways to integrate payments depending on the required level of control and customer journey:

    • Hosted Checkout: Best for launching a checkout experience from a site or app using the JavaScript Plugin.
    • Payment Links: Best for sharing a hosted payment URL with customers; requires no technical integration.
    • REST API: Best for backend-driven server-to-server operations such as payments, refunds, tokens, and sessions.

  5. Choose between Zenith Payments Merchant and Customer APIs

    Zenith Payments provides two distinct REST APIs depending on the integration goal:

    1. Merchant APIs: Used for merchants integrating payments, pre-authorizations, refunds, and other core payment functions. These require ZenPay-issued credentials.
    2. Customer APIs: A self-service REST API designed for a merchant's own customers. These require a Bearer token issued through the merchant's portal account.

  6. Understand Zenith Batch Payments concepts

    Batch payments allow merchants to submit multiple payment instructions in a single operation, which is ideal for recurring billing, invoice settlements, or payroll disbursements. This is recommended when payments are not latency-sensitive and are ready at a specific time (e.g., end-of-day). It is not suitable for interactive checkouts or customer-triggered payments requiring immediate responses. Conceptually, a batch contains a list of instructions (amount, customer reference, payment method/token); Zenith processes these and emits results via callbacks, webhooks, or the GET /v2/payments endpoint. Note: Specific file formats and endpoints are not yet documented; contact a Zenith representative for specifications.

  7. Enable Apple Pay for self-hosted plugins

    If you host the Zenith Payments plugin on your own domain (rather than using Payment Links), you must complete a domain verification process:

    1. Provide the domain URL (e.g., www.zenpay.com.au) to the Zenith Payments Integrations Team.
    2. Upload the verification file provided by Zenith to the following path on your server: /.well-known/apple-developer-merchantid-domain-association.
    3. Confirm the upload with Zenith to register the domain with Apple Pay.

  9. Implement backend best practices for payment callbacks

    When handling payment callbacks, follow these security and reliability constraints:

    • Security: Only accept POST requests over HTTPS. Never trust callback data or redirects as the final truth without validating the validationCode server-side. Never expose credentials or validation logic to the browser.
    • Idempotency: Treat callbacks as idempotent. Use the merchantUniquePaymentId to prevent double-processing payments.
    • User Experience: If a user is redirected back to your site before the callback validation is complete, display a 'pending' or 'confirming' state.

  10. Validate Zenith Payments callback integrity

    To verify a callback, regenerate the validationCode using a SHA3-512 hash of the following seven pipe-separated fields in this exact order:

    apiKey|userName|password|mode|paymentAmount|merchantUniquePaymentId|reference

    Validation Rules:

    • The first six fields are identical to those used in the original fingerprint hash.
    • The final field (reference) replaces the timestamp used in the fingerprint.
    • For Mode 1 (Tokenise), the reference is the Token output parameter.
    apiKey|userName|password|mode|paymentAmount|merchantUniquePaymentId|reference

  11. Implement PayTo real-time bank payments

    PayTo allows real-time payments from Australian bank accounts via the New Payment Platform (NPP).

    Integration Flow:

    1. Collection: Use the Payment Plugin in Tokenisation mode. The customer enters their Account Name, BSB, and Account Number.
    2. Mandate: The customer must approve the mandate in their banking app. The account should be marked as "Pending Mandate Approval" in the merchant's system until confirmed.
    3. Processing: Once active, send the PayTo token/proxy during transaction processing. Transactions are processed instantly.

  12. Harden ZenPay integration security

    Follow these best practices to secure your payment integration:

    • Bot and Fraud Protection: Use an invisible challenge-response system (e.g., Cloudflare Turnstile or Google reCAPTCHA v3) to validate users before calling zpPayment(...).
    • CSRF Protection: Use unique, cryptographically strong server-generated CSRF tokens for every payment initiation request. Validate all transaction details on the backend before passing them to the plugin.
    • Content Security Policy (CSP): Implement a strict CSP to restrict which domains can execute scripts on your page.