# Zenith Payments Developer Documentation > Payment solutions for every industry ## 1.129 ### Release 1.129 February 19, 2026 · 4 min read [![Zenith Product Team](/img/team-avatar.svg)](/release-notes/authors/product) [Zenith Product Team](/release-notes/authors/product) Product Management #### ZenPay Release 1.129[​](#zenpay-release-1129 "Direct link to ZenPay Release 1.129") This release introduces new capabilities for issuing credits back to customers, strengthens payment and callback reliability, and expands customer verification options. This release introduces new capabilities for issuing credits back to customers, strengthens payment and callback reliability, and expands customer verification options. We’ve also delivered significant improvements to points and rewards management, especially for multi‑currency programs, and enhanced customer support and profile management across B2Bpay and Fionix experiences. ##### Payments & Settlements[​](#payments--settlements "Direct link to Payments & Settlements") * Added support for issuing **credits back to customers** (in addition to refunds) for selected merchants, including configurable daily limits and API access for requesting and tracking credits. This gives merchants a controlled way to correct payments while maintaining strong financial and risk controls. * Improved processing of payment statuses * Improved processing of batch payments. * Fixed an issue where some **B2B payments remained in a pending state** even after being approved, ensuring that once a payment is approved it progresses correctly and the customer’s card is only charged when the status is updated. * Added better handling of **PayTo‑related terms and snippets** in the payment plugin so that the correct terms and conditions are shown when specific payment options (such as deferred payment methods) are selected. ##### Points, Rewards & Programs[​](#points-rewards--programs "Direct link to Points, Rewards & Programs") * Enhanced the **Manage Rewards** experience with a points currency column, currency‑aware filters, CSV export updates, and summaries that respect the chosen currency. This makes it easier for administrators to understand and report on rewards activity per currency. * Added support for **Velocity Business Flyer** as a points transfer partner, including connection and transfer capabilities, so eligible customers can link membership and transfer points to this program. * Fixed issues where **QBR points redemptions** and other partner redemption files were not being generated or reflected correctly in redemption history, ensuring that points earned and redeemed appear accurately in customer and admin views. * Addressed minor discrepancies in **points statuses** in history tables (for example, “Awarded” vs “Redeemed”) so that points histories correctly reflect the underlying action (conversion or redemption). ##### Customer Experience & Support[​](#customer-experience--support "Direct link to Customer Experience & Support") * Ensured that updates to **business address fields** (such as additional address lines) in the customer profile are properly saved and reflected in the UI. * Improved customer profile handling for **New Zealand region customers**, fixing issues where the country would revert to Australia and state/province options were limited, so addresses can now be correctly maintained for non‑Australian customers. * Implemented a dedicated **Customer Support** experience in the Fionix/B2Bpay 2.0 platform, including a support entry point on logged‑in pages and a support page that offers clear options to email, call, or access FAQs, plus a structured “Send us an email” form with validation and prefilled profile details where available. * Fixed small user interface misalignments and text issues in customer‑facing flows (for example, aligning screens to Figma designs and correcting labels) to provide a more polished and consistent experience. * Adjusted CSV exports and labels for customer data (for example, **date of birth formatting and column names**) to be clearer and more consistent with other areas of the platform. ##### Integrations & Technical Improvements[​](#integrations--technical-improvements "Direct link to Integrations & Technical Improvements") * Added **PayTo status information** to callback URLs used by integrators when PayTo is used for one‑off payments or tokenisation, making it easier for integrated systems to understand the current mandate status without additional lookups. * Ensured that **PayTo token information** is available in relevant tokenisation and status webhooks, enabling integrators to link webhook notifications to the correct tokenised account without storing raw bank account details, and improving security by obfuscating account information where appropriate. * Resolved an issue where certain **callback notifications** (for example, for specific TravelPay merchants) were not always received by integrators, improving the reliability and traceability of callbacks for successfully processed transactions. * Addressed issues with tokenisation in specific scenarios where customers could encounter a **“please contact administrator”** error during card token creation, ensuring a smoother tokenisation experience and correcting underlying configuration dependencies. * Added a dedicated **TravelPay Shield flag** on applicable transactions so program and compliance managers can more easily identify and report on transactions that qualify for this protection in admin and merchant portals. * Clarified the behaviour and documentation of selected **API endpoints** (including session‑related endpoints and transaction type descriptions) so integrators have a more accurate and complete view of available responses and transaction types. **Tags:** * [Payments](/release-notes/tags/payments "Payment processing, settlements, and transaction changes") * [Integrations](/release-notes/tags/integrations "Third-party integrations, webhooks, and API updates") * [Rewards](/release-notes/tags/rewards "Points, rewards, and accelerator program changes") * [B2Bpay](/release-notes/tags/b2bpay "B2Bpay-specific features and fixes") [Edit this page](https://github.com/ianmenethil/docusaurus-2/edit/main/release-notes/1.129.md) Last updated on **Oct 26, 2026** by **Ian Menethil** --- ## 1.130 ### Release 1.130 March 19, 2026 · 4 min read [![Zenith Product Team](/img/team-avatar.svg)](/release-notes/authors/product) [Zenith Product Team](/release-notes/authors/product) Product Management #### ZenPay Release 1.130[​](#zenpay-release-1130 "Direct link to ZenPay Release 1.130") This release improves the reliability of PayTo settlements and payment approvals, enhances B2Bpay's integration with accounting systems such as Xero, and makes points balances and rewards behaviour clearer for customers. This release improves the reliability of PayTo settlements and payment approvals, enhances B2Bpay’s integration with accounting systems such as Xero, and makes points balances and rewards behaviour clearer for customers. We’ve also strengthened program/site awareness for customers and payments, improved customer sign‑up and support experiences, and delivered performance and webhook upgrades for integrators. ##### Payments & Settlements[​](#payments--settlements "Direct link to Payments & Settlements") * Fixed an issue where some PayTo settlements appeared on the wrong date in ZenPay, so settlement dates now more accurately reflect when funds reach your bank and when merchants should expect settlement. * Resolved a browser-side error that could appear when making a one-off customer payment, reducing noise and friction during checkout. * Improved system performance for certain payment processes ##### B2Bpay & Accounting Integrations[​](#b2bpay--accounting-integrations "Direct link to B2Bpay & Accounting Integrations") * Corrected how failed B2Bpay payments are reflected in Xero so failed transactions no longer appear as paid and invoices remain outstanding until successfully settled. * Added a new capability in the core API to expose current account settings for connected accounting partners (such as Xero), supporting more reliable configuration flows and future self‑service editing of these settings. * Updated payment behaviour so that when valid accounting partner details are passed for eligible scenarios, unnecessary 3‑D Secure prompts are avoided, reducing friction in trusted flows while keeping security expectations unchanged elsewhere. * Redirected legacy B2Bpay quick registration links to the current sign‑up experience on the new platform, providing a more consistent onboarding journey and ensuring better data collection for new merchants. ##### Points, Rewards & Programs[​](#points-rewards--programs "Direct link to Points, Rewards & Programs") * Resolved mismatches between “Available Points” on dashboards and the latest balance in points history so customers see a single, accurate view of their points at any time. * Fixed an issue where some Qantas Points balances could display as zero despite successful accrual, restoring correct visibility and ensuring customers can redeem their earned Qantas Points. * Improved handling of failed redemptions so rejected operations no longer increase redeemed points totals, keeping redemption history and balances accurate. * Addressed scenarios where alternative‑fee transactions and accelerator programs did not correctly allocate points, ensuring that points and rewards are now consistently applied in those cases. ##### Customer Experience & Support[​](#customer-experience--support "Direct link to Customer Experience & Support") * Fixed issues that prevented some newly created users from setting or resetting their password, and corrected “Forgot password” emails so they consistently include a working reset link. * Improved sign-up forms by clarifying website URL handling and “I don’t have a website” options, and by making validation and consent checkbox behaviour more reliable, reducing confusion and failed sign‑ups. * Improved wallet and payee management so customers can successfully change their default payment method without losing nicknames, and removing a payee no longer displays a misleading error when the operation succeeds. * Ensured logged-out customers can submit support enquiries reliably via the “Send us an email” form, and that the support team receives the customer’s own email address as the sender, improving follow‑up and response accuracy. * Updated support enquiry categories configured in admin tools so they correctly appear in the customer-facing support page, helping customers choose the most relevant topic when contacting support. ##### Integrations & Technical Improvements[​](#integrations--technical-improvements "Direct link to Integrations & Technical Improvements") * Made webhook processing more robust with improved reliability, logging and retry handling, and broadened coverage of state changes, including PayTo tokenisation and other lifecycle events, giving integrators a more complete and dependable event stream. * Corrected PayTo tokenisation status events so creating a new token is now clearly reported as a new event (rather than an update), making it easier for integrated systems to interpret token lifecycle events accurately. * Improved handling of SlicePay data. * Resolved issues affecting session creation and redirect flows for certain integrated payment solutions, improving the stability of hosted payment flows and reducing errors when launching payments from connected platforms. **Tags:** * [Payments](/release-notes/tags/payments "Payment processing, settlements, and transaction changes") * [Integrations](/release-notes/tags/integrations "Third-party integrations, webhooks, and API updates") * [Rewards](/release-notes/tags/rewards "Points, rewards, and accelerator program changes") * [B2Bpay](/release-notes/tags/b2bpay "B2Bpay-specific features and fixes") [Edit this page](https://github.com/ianmenethil/docusaurus-2/edit/main/release-notes/1.130.md) Last updated on **Oct 26, 2026** by **Ian Menethil** --- ## Archive ### Archive ##### 2026[​](#2026 "Direct link to 2026") * [February 19](/release-notes/1.129.md) [ - ](/release-notes/1.129.md) [Release 1.129](/release-notes/1.129.md) * [March 19](/release-notes/1.130.md) [ - ](/release-notes/1.130.md) [Release 1.130](/release-notes/1.130.md) --- ## Get Started ### Choose Your Integration ZenPay supports multiple integration paths depending on how much control you need and how much implementation work you want to do. Use this page to choose the right starting point before going deeper into the documentation. *** #### Use Hosted Checkout when[​](#use-hosted-checkout-when "Direct link to Use Hosted Checkout when") Choose **Hosted Checkout** when: * you are integrating ZenPay into your own website or app * you want to launch checkout using the JavaScript Plugin * you want modal / iframe or redirect checkout behaviour * you want ZenPay to host the payment UI while your backend remains responsible for validation and payment state This is the best option when you want an integrated customer experience without building and hosting your own payment form. ![Payment Plugin demo2](/assets/images/demo-plugin-d672468623160b57226d1806ae3c478b.webp) ##### Go to[​](#go-to-hosted-checkout "Direct link to Go to") * [Hosted Checkout](/docs/integration-options/hosted-checkout.md) * [Hosted Checkout Pathway](/docs/integration-options/hosted-checkout/hosted-checkout-pathway.md) *** #### Use Payment Links when[​](#use-payment-links-when "Direct link to Use Payment Links when") Choose **Payment Links** when: * you want a direct hosted checkout page link * you want low setup effort * you do not want to build an integrated checkout flow * you want a faster path to accepting payments with minimal development work This is the best option when the merchant wants a hosted-link model instead of embedding checkout into their own site or application. ![Payment Link Demo](/assets/images/payment-link-demo-91fc23cdf3cbaf6089e25bda39570fce.webp) ##### Go to[​](#go-to-payment-links "Direct link to Go to") * [Payment Links](/docs/integration-options/payment-links.md) * [Setup & Branding](/docs/integration-options/payment-links/setup-and-branding.md) * [Notifications](/docs/integration-options/payment-links/notifications.md) *** #### Use REST API when[​](#use-rest-api-when "Direct link to Use REST API when") Choose **REST API** when: * you need server-to-server payment operations * you need deeper backend control * you want to manage payment lifecycle actions programmatically * you are building backend-led integrations rather than browser-launched checkout This is the best option when your integration is primarily backend-driven. ##### Go to[​](#go-to-rest-api "Direct link to Go to") * [REST API](/docs/integration-options/rest-api.md) * [Authentication](/docs/integration-options/rest-api/authentication.md) * [Errors](/docs/integration-options/rest-api/errors.md) *** #### Quick rule of thumb[​](#quick-rule-of-thumb "Direct link to Quick rule of thumb") * **Hosted Checkout** → integrated browser checkout * **Payment Links** → hosted payment link * **REST API** → backend-controlled integration If you are unsure, start with the option that matches how the payment flow begins: * from **your website/app** → Hosted Checkout * from a **shared payment link** → Payment Links * from **your backend systems** → REST API --- ### Integration Checklist Use This Checklist Check off each item before going live. This is an example list as each integration can be unique. Your progress is saved in this browser and will persist across sessions. *** #### ✅ Production Approval[​](#-production-approval "Direct link to ✅ Production Approval") | Field | Details | | ------------------------ | ------- | | Integration completed by | \_\_ | | Date | \_\_ | | Approved by | \_\_ | | Go-live date | \_\_ | Ready to Launch? When all items are checked, you're ready for production! Remember to monitor closely for the first week. *** #### 🆘 Support Contacts[​](#-support-contacts "Direct link to 🆘 Support Contacts") ##### Technical Issues (integration related)[​](#technical-issues-integration-related "Direct link to Technical Issues (integration related)") * **Email:** * **Portal:** [Submit ticket](https://portal.zenithpayments.com.au) #### 📚 Additional Resources[​](#-additional-resources "Direct link to 📚 Additional Resources") * [Choose Your Integration →](/docs/get-started/choose-your-integration.md) * [Error Codes Reference →](/docs/integration-options/rest-api/errors.md) * [API Reference →](/docs/integration-options/rest-api.md) #### 🎉 Congratulations\![​](#-congratulations "Direct link to 🎉 Congratulations!") You're ready to launch! This checklist ensures a smooth, secure integration. **Questions before launch?** Contact **After launch?** We're here to help, please reach out any time! --- ## Integration Guides ### Batch Payments Draft — needs product verification This page is a first-pass draft describing batch payments at a conceptual level. All specifics — file format, submission channel, processing SLA, error response format — require product team confirmation before publication. Do not treat any claim on this page as authoritative until this admonition is removed. #### What are batch payments?[​](#what-are-batch-payments "Direct link to What are batch payments?") Batch payments let merchants submit multiple payments in a single operation rather than calling the API once per transaction. This pattern is useful for recurring billing runs, invoice settlement cycles, payroll-style disbursements, and any other workflow where many payments are processed at a known time. #### When to use batch payments[​](#when-to-use-batch-payments "Direct link to When to use batch payments") Batch processing fits scenarios where: * Multiple payments are ready at the same time (end-of-day, end-of-cycle, after an invoice run) * The timing of each individual payment is not latency-sensitive * Merchant-side batching simplifies reconciliation compared to per-transaction reporting Batch processing is **not** a good fit for: * Interactive checkout flows * Per-customer payments triggered by customer action * Any scenario requiring an immediate per-transaction response #### How it works (high level)[​](#how-it-works-high-level "Direct link to How it works (high level)") At a conceptual level, a batch submission contains a list of payment instructions, each with its own amount, customer reference, and payment method or stored token. Zenith processes each entry, returns a batch-level status, and emits per-transaction results through the usual callback, webhook, or `GET /v2/payments` paths. Implementation details not yet documented The exact batch format, submission endpoint, response schema, error handling, retry semantics, and pricing model for batch payments are not yet documented here. Contact your Zenith integration representative for current batch payment specifications. #### Related[​](#related "Direct link to Related") * [REST API](/docs/integration-options/rest-api.md) * [Common API Patterns](/docs/integration-options/rest-api/common-api-patterns.md) * [Payment Reconciliation](/docs/integration-guides/reconciliation.md) Under Construction The hamsters powering this page called in sick today. CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION --- ### Best Practices General recommendations for building robust, secure integrations with Zenith Payments. These apply across every integration path — Hosted Checkout, Payment Links, and the REST API. For Hosted Checkout specific guidance (fingerprint handling, plugin initialisation errors, `callbackUrl` validation), see [Hosted Checkout — Best Practices](/docs/integration-options/hosted-checkout/best-practices.md#best-practices). #### Security[​](#security "Direct link to Security") ##### Rate Limiting and Velocity Checks[​](#rate-limiting-and-velocity-checks "Direct link to Rate Limiting and Velocity Checks") Rate limiting should be implemented at both the IP and session levels. You should restrict the number of payment attempts a single user can make within a specific timeframe (e.g. no more than 3 attempts per 15 minutes). Furthermore, implement velocity checks on your backend to monitor for spikes in overall transaction volume or a high frequency of "Declined" responses. If your system detects an unusual pattern — such as 50 declines in 60 seconds — it should automatically trigger a temporary "circuit breaker" to halt all processing until the threat is mitigated. ##### Secure Credential Management[​](#secure-credential-management "Direct link to Secure Credential Management") Merchant-specific credentials — API keys, usernames, passwords, and payment tokens — must be stored securely on your infrastructure (e.g. environment variables or a secrets manager) and never transmitted to the client. Treat your backend as the source of truth for all secrets; the frontend should never hold or log authentication material. This principle applies regardless of integration path: * **Hosted Checkout** — server generates the fingerprint, frontend only receives the launch-safe payload * **Payment Links** — no client-side secrets at all; the link is the only thing customers see * **REST API** — all calls originate server-to-server from your trusted backend, never from browser code #### Validating Payments[​](#validating-payments "Direct link to Validating Payments") We provide multiple avenues to validate payments, depending on payment method, including `redirectUrl`, `callbackUrl`, webhook, API response, and `GET` calls. In general, we recommend using multiple data points to ensure validity and reduce the chance of not reconciling correctly. ##### Post-Payment Verification[​](#post-payment-verification "Direct link to Post-Payment Verification") Whilst API payments will result in an immediate response, both API and plugin payments can be additionally verified, or additional details checked with our webhook, which will trigger when the `paymentStatus`, `payToStatus`, and/or `isPaymentSettledToMerchant` parameters change. This can be useful in tracking payment state or PayTo token updates/settlement. These parameters can also be checked with a `GET` call to the `/v2/payments` API endpoint. #### Parameter Field Validation[​](#parameter-field-validation "Direct link to Parameter Field Validation") Zenith Payments performs basic field validation for parameters, but it is vital to validate all data before it is sent to Zenith Payments. This includes: * ensuring emails and phone numbers are formatted correctly * payment amounts are passed as numbers (floats usually) and not strings which can be ambiguous to type-cast (`3456.99` is preferred over `"3,456.99"` which may cause validation issues) * ensuring customer references do not contain special characters By enforcing strict validation on the frontend and backend, you ensure that the data returned in your post-payment callbacks is predictable and matches your internal records. This proactive approach minimises unexpected "edge case" errors and ensures that your automated reporting and reconciliation processes remain accurate. #### Error Handling[​](#error-handling "Direct link to Error Handling") Whilst Zenith Payments performs its own data validation, it is important to have logic to handle unexpected data from responses, and error handling for all payment outcomes, including Successful, Failure, Error, In Progress, and Pending transactions. There should be logic to handle any non-success responses gracefully — including unknown or unrecognised fields — to ensure system stability and the best user experience for customers. Some error messaging we provide is passed along from upstream providers and can depart from regular error messaging. This means it is important to not hard-code error responses as they change from time to time, often without being communicated. We also recommend having robust and helpful logs to aid in troubleshooting internally, and when working with us to cover any unexpected behaviour. The following details will greatly aid in getting to the bottom of any issues: * Exact time in UTC * IP address of user * Payment payload * Any returned responses * Screenshots of the error #### Common Pitfalls[​](#common-pitfalls "Direct link to Common Pitfalls") Common mistakes that surface during integration or after deployment, and how to avoid them. ##### Hardcoding Parameter Responses[​](#hardcoding-parameter-responses "Direct link to Hardcoding Parameter Responses") Whilst some errors are generated by our system, others are generated by upstream payment partners (like messages from card issuers and banks). Due to this, and other factors, we do not recommend hard-coding any error messages into your system without the ability to gracefully handle unexpected responses in those fields. We endeavour to keep breaking changes to a bare minimum, but parameter responses may change from time to time, and that should be factored in for graceful failures. ##### Webhook Parameter Casing[​](#webhook-parameter-casing "Direct link to Webhook Parameter Casing") In our current version of our webhook (as of February 2026), there are a couple of spelling mistakes in our webhook parameter names. The parameter labels in this documentation are correct, and we have noted these in the description as well. The other thing to note is that **webhooks use upper camel case** (`VariableName`) while **API and callback responses use lower camel case** (`variableName`). Your integration should account for this casing difference when parsing payloads from each surface. ##### Assuming Callback, Webhook, and API responses will have identical payloads[​](#assuming-callback-webhook-and-api-responses-will-have-identical-payloads "Direct link to Assuming Callback, Webhook, and API responses will have identical payloads") Callbacks, Webhooks, and API responses all have subtley different payloads. Callbacks and Webhooks are largely the same data with the main change being camelCase vs UpperCamelCase. API responses see [Payment and Transaction Codes](/docs/resources/payment-and-transaction-codes.md) for more detail on some parameters and where they differ. --- ### Common Payment Flows Use this page to choose the Zenith flow that best matches your implementation. Each flow below explains when to use it, what Zenith surface is involved, and where to go next for the full guide. #### Payment Plugin Checkout Flow[​](#payment-plugin-checkout-flow "Direct link to Payment Plugin Checkout Flow") Use this flow when you want Zenith to collect payment details in a hosted plugin experience and return the outcome to your system. This is the lowest-friction path for one-off payments. Your server prepares the payment request, handles fingerprint generation and credentials, and receives the result through your callback handling. The payer completes the payment in the plugin, and your system validates the outcome using the callback, webhook, or a follow-up API check where needed. Use this flow when: * you want a hosted checkout rather than building card or bank account collection yourself * you need a one-off payment flow with callback-based validation * you want access to plugin-supported payment methods such as cards, bank flows, PayTo, or supported wallets Related guides: * [Get Started](/docs/get-started/choose-your-integration.md) * [Payment Plugin](/docs/integration-options/hosted-checkout.md) * [Callbacks and Validation](/docs/integration-options/hosted-checkout/callbacks.md#callbacks-overview) * [Best Practices](/docs/integration-guides/best-practices.md) #### API Tokenised Payment Flow[​](#api-tokenised-payment-flow "Direct link to API Tokenised Payment Flow") Use this flow when you need to charge a stored payment method from your own application logic. The common pattern is to first collect and tokenise the payment method, store the returned token safely in your system, and then create future payments by API using that token. This flow is suitable when your platform needs more control over timing, scheduling, retries, or customer account management. Use this flow when: * you need recurring or operator-initiated payments * you want to link stored payment methods to a customer or internal entity in your system * you need backend-controlled charging rather than payer-driven checkout each time Operational notes: * keep token storage and charge initiation on trusted backend systems * track payment outcomes using API responses plus webhook or follow-up validation where relevant * define your retry and reconciliation process before going live Related guides: * [Recurring Payments](/docs/integration-guides/recurring.md) * [Best Practices](/docs/integration-guides/best-practices.md) * [Webhooks](/docs/resources/webhooks.md) #### Pre-Authorisation Payment Flow[​](#pre-authorisation-payment-flow "Direct link to Pre-Authorisation Payment Flow") Use this flow when you need to place a hold on funds first and capture or void that amount later. Zenith's pre-authorisation workflow is a hybrid pattern. The payer enters card details through the Payment Plugin in pre-authorisation mode, your system stores the returned `preauthReference`, and later API calls are used to check status, capture funds, or void the hold. Use this flow when: * the final amount is confirmed after the initial authorisation step * you need the ability to capture later or partially capture against an authorised amount * your operational process requires an explicit hold-before-capture model Related guides: * [Pre-Authorisation](/docs/integration-guides/pre-auth.md) * [Payment Plugin](/docs/integration-options/hosted-checkout.md) * [Best Practices](/docs/integration-guides/best-practices.md) #### Batch Payment Flow[​](#batch-payment-flow "Direct link to Batch Payment Flow") Use this flow when you need to process a group of payments as part of an operational run rather than one payer interaction at a time. Batch-style workflows are typically driven from your backend or operations process. They are best suited to cases where your team prepares a defined set of payments, runs them through a controlled process, and then reconciles the results after the run completes. Use this flow when: * you process many payments as part of a scheduled or operator-managed run * you need strong operational controls, logging, and reconciliation around the run * your workflow is centered on back-office processing rather than individual payer checkout Known limitation: * this page only summarizes the flow shape; implementation details should be confirmed against the specific batch process you are using Related guides: * [Batch Payments](/docs/integration-guides/batch-payments.md) * [Payment Reconciliation](/docs/integration-guides/reconciliation.md) #### Recurring Payment Flow[​](#recurring-payment-flow "Direct link to Recurring Payment Flow") Use this flow when you need to debit a customer on a repeated schedule using a previously stored payment method. Recurring payments usually start with tokenisation, followed by secure token storage in your system and scheduled backend API calls to create each new payment. Your implementation should also define how failed payments, retries, customer communication, and reconciliation are handled. Use this flow when: * you bill on a subscription, instalment, or scheduled-debit model * you need to associate tokens with a customer, contract, booking, or account in your own system * you want payment creation to happen from your backend on a defined schedule Related guides: * [Recurring Payments](/docs/integration-guides/recurring.md) * [Payment Reconciliation](/docs/integration-guides/reconciliation.md) #### Choosing the Right Flow[​](#choosing-the-right-flow "Direct link to Choosing the Right Flow") Use this quick guide if you are deciding where to start: * Choose Payment Plugin Checkout when the payer is present and you want Zenith to host payment collection. * Choose API Tokenised Payment when you need future backend-initiated charges using a stored payment method. * Choose Pre-Authorisation when you need to hold funds first and capture or void later. * Choose Batch Payment when your process is run-oriented and managed from operations or backend systems. * Choose Recurring Payment when charges happen on a defined schedule. If you are still deciding, start with [Get Started](/docs/get-started/choose-your-integration.md) and [Best Practices](/docs/integration-guides/best-practices.md), then move into the specific guide for your target workflow. --- ### Pre-Authorisation Guide Zenith supports Pre-Authorisation for certain payment methods (primarily Visa, Mastercard, and Amex). This puts a hold of an amount up to a configurable maximum on the payer's card and remains valid for up to 5 days. This is achieved by creating a Pre-Auth Reference, which should be securely stored, for further processing (status check, charge, void/cancel). Integrating with our Pre-Auth implementation requires a hybrid approach between collecting the card details via our Payment Plugin, and then processing it via API calls. #### Creating the Pre-Auth Reference[​](#creating-the-pre-auth-reference "Direct link to Creating the Pre-Auth Reference") The Pre-Auth Reference can be created via our Payment Plugin using mode 3 (see [Plugin Documentation](/docs/integration-options/hosted-checkout.md) for more details). When the payer enters their card details, a Pre-Auth reference is created for further processing. 1. Payer enters card details and selects Proceed Screenshot: Pre-auth step 1 2. Payer is presented with any relevant fees during transactions and selects "Pay Now" which will finalise the pre-authorisation and return the `preauthReference` via `callbackUrl` or Webhook. Screenshot: Pre-auth step 2 **Example Callback response:** ```json { "response": { "preauthReference": "103502", "customerName": "John Snow", "customerReference": "REFERENCE1", "preauthStatus": 3, "preauthStatusString": "Successful", "baseAmount": 500, "accountOrCardNo": "411111XXXXXX1111", "paymentAccount": "Card", "processingDate": "2026-02-06T15:24:12.083", "processorReference": "0c051e1c13ae94af3d89", "failureCode": "", "failureReason": "", "paymentCard": "Visa", "merchantUniquePaymentId": "533fe4ce-372d-41c3-9de2-59d8da1e5d98", "merchantCode": "ZenTest1", "transactionSource": 61, "transactionSourceString": "Public_Customer_OnlineOneOffPreauth", "customerFee": 9.5, "preauthAmount": 509.5, "cardCategory": "International Cards", "preauthExpiryAt": "2026-02-11T15:24:12.083" }, "validationCode": "3413955ed8e88251e7e41fbeaf67ee764254f3713c7a0f68a1509b94fb6a3a5a1f6f7fca573fa623ce8f35a42a854f326de7492093b64f1820695190f314a089" } ``` #### Checking Status and Current Balance of Reference[​](#checking-status-and-current-balance-of-reference "Direct link to Checking Status and Current Balance of Reference") You can check the status of the Pre-Auth Reference by making a GET call to `/v2/preauths/{preauthReference}` The response contains details about the payment including expiry time, available balance, and basic identifying data. **Example API response:** ```json { "preauthReference": "101996", "customerName": "Tyrande Whisperwind", "customerReference": "CR-MKV53Q34-P0E", "preauthStatus": "Successful", "baseAmount": 100, "fundsToMerchant": 0, "customerFee": 10, "merchantFee": 0, "preauthAmount": 110, "accountOrCardNo": "411111XXXXXX1111", "paymentAccount": "Card", "processingDate": "2026-01-26T23:24:42.603", "processorReference": "88237585328d654c33b3", "isPaymentSettledToMerchant": false, "paymentCard": "Visa", "additionalReference": "API Example Test - Preauth", "merchantName": "Menethil", "merchantCode": "1337", "merchantUniquePaymentId": "PRE-1769430280144", "isPaymentRetryScheduled": false, "isPaymentRecalled": false, "isPaymentRefunded": false, "cardCategory": "International Cards", "transactionType": 9, "transactionTypeDisplay": "9", "isPaymentChargeBacked": false, "preauthExpiryAt": "2026-01-31T23:24:42.603", "remainingPreauthAmount": 110 } ``` #### Charging (Capturing) the Pre-Auth Reference[​](#charging-capturing-the-pre-auth-reference "Direct link to Charging (Capturing) the Pre-Auth Reference") To make a payment using the Pre-Auth hold amount, you can make a POST call to `/v2/preauths/{preauthReference}/captures`. You can make a charge up to the available amount on the Reference. Multiple partial payments can also be made. **Example API response:** ```json { "paymentReference": "101997", "customerName": "Tyrande Whisperwind", "customerReference": "CR-MKV53Q34-P0E", "paymentStatus": "Successful", "baseAmount": 100, "fundsToMerchant": 100, "customerFee": 10, "merchantFee": 0, "paymentAmount": 110, "accountOrCardNo": "411111XXXXXX1111", "paymentAccount": "Card", "processingDate": "2026-01-26T23:24:45.7599174", "settlementDate": "2026-01-27T00:00:00", "processorReference": "84484d5fd4ffac1f6aff", "isPaymentSettledToMerchant": false, "paymentCard": "Visa", "merchantName": "Menethil", "merchantCode": "1337", "merchantUniquePaymentId": "CAP-1769430283329", "isPaymentRetryScheduled": false, "isPaymentRecalled": false, "isPaymentRefunded": false, "transactionType": 1, "transactionTypeDisplay": "Charge", "isPaymentChargeBacked": false, "paymentSourceDisplay": "Api Tokenised Payment", "preauthExpiryAt": "2026-01-31T23:24:42.603", "remainingPreauthAmount": 0 } ``` #### Voiding the Pre-Auth Reference[​](#voiding-the-pre-auth-reference "Direct link to Voiding the Pre-Auth Reference") If you would like to void/cancel the Pre-Auth Reference and return remaining funds to the payer's account you can make a PUT call to `/v2/preauths/{preauthReference}/voids`. Once a Reference is voided, it can not be reactivated, but it's status can still be checked. **Example API response:** ```json { "preauthReference": "101998", "status": "Successful" } ``` --- ### Payment Reconciliation Reconciliation is the process of matching payments processed by Zenith against records in your own system. Zenith supports three complementary approaches, and most merchants use a combination depending on volume and operational needs. #### Approach 1: Callback-based reconciliation[​](#approach-1-callback-based-reconciliation "Direct link to Approach 1: Callback-based reconciliation") When a Hosted Checkout payment completes, Zenith sends a server-to-server callback containing the full payment result including `merchantUniquePaymentId`, `paymentStatus`, `baseAmount`, `processingDate`, `settlementDate`, and a `validationCode` that authenticates the payload. **Use for:** near-real-time reconciliation of Hosted Checkout flows. **Strengths:** immediate, includes validation code for tamper protection, no polling required. **Limitations:** only covers transactions that used a `callbackUrl`. Network failures or merchant-side outages may delay or drop callbacks — you still need a fallback. See [Callbacks and Validation](/docs/integration-options/hosted-checkout/callbacks.md#callbacks-overview) for the full payload shape and validation flow. #### Approach 2: Webhook-based reconciliation[​](#approach-2-webhook-based-reconciliation "Direct link to Approach 2: Webhook-based reconciliation") The Zenith webhook fires when specific payment state parameters change — including `paymentStatus`, `payToStatus`, and `isPaymentSettledToMerchant`. Unlike callbacks (which are tied to a single transaction and its `callbackUrl`), webhooks are merchant-wide and trigger on state transitions across all transactions. **Use for:** tracking settlement status, PayTo mandate lifecycle updates, and events that happen *after* the initial payment completes (settlement, dispute, refund completion). **Strengths:** covers events that callbacks miss (settlement transitions, PayTo status changes, post-payment updates). **Limitations:** webhook delivery is best-effort; fall back to the API for authoritative state. See [Webhooks](/docs/resources/webhooks.md) for subscription and payload details. #### Approach 3: API-based reconciliation[​](#approach-3-api-based-reconciliation "Direct link to Approach 3: API-based reconciliation") The `GET /v2/payments` endpoint returns payment records and can be queried on-demand. This is the **authoritative** source of payment state — use it to verify any callback or webhook, backfill missed events, or run periodic reconciliation sweeps. **Use for:** end-of-day reconciliation runs, investigation of individual payments, recovery from missed webhooks, any audit process that needs a source of truth. **Strengths:** deterministic, replayable, authoritative. **Limitations:** requires merchant-side scheduling; higher overhead than event-driven approaches. See the [REST API Reference](/docs/integration-options/rest-api.md) for the `GET /v2/payments` request and response schema. #### Recommended reconciliation pattern[​](#recommended-reconciliation-pattern "Direct link to Recommended reconciliation pattern") Most merchants should combine all three approaches: 1. **Real-time:** process callbacks as transactions complete (Approach 1). 2. **Asynchronous state updates:** subscribe to webhooks for settlement, PayTo status, and post-payment events (Approach 2). 3. **Daily reconciliation sweep:** run a scheduled job that queries `GET /v2/payments` for the previous day and compares against your local records to catch any missed events (Approach 3). #### Edge cases to handle[​](#edge-cases-to-handle "Direct link to Edge cases to handle") * **Callbacks received out of order or duplicated:** use `merchantUniquePaymentId` as an idempotency key. * **Partial settlement:** `isPaymentSettledToMerchant` may flip `false → true` days after the initial payment; treat settlement as a separate event. This is when funds are released to the merchant and can be used to track successful bank payments. * **PayTo mandate cancellation:** a mandate active at payment time can later be cancelled by the customer in their bank app, triggering a webhook. Your reconciliation loop should handle status changes on *existing* records. * **Refunds:** refund requests are manually approved, so the refund state on a payment record can change days after the refund was requested. Periodic API reconciliation is the only reliable way to track this. #### Related[​](#related "Direct link to Related") * [Callbacks and Validation](/docs/integration-options/hosted-checkout/callbacks.md#callbacks-overview) * [Webhooks](/docs/resources/webhooks.md) * [REST API](/docs/integration-options/rest-api.md) --- ### Recurring Payments #### What are recurring payments?[​](#what-are-recurring-payments "Direct link to What are recurring payments?") Recurring payments charge a previously tokenised payment method on a schedule — for example, a monthly subscription, an annual renewal, or a weekly instalment. Zenith supports recurring payments against stored cards and PayTo mandates. #### How the pattern works[​](#how-the-pattern-works "Direct link to How the pattern works") Recurring billing in Zenith follows a two-step pattern: 1. **Tokenise the payment method once.** The customer enters their card or bank details on a hosted flow (Hosted Checkout Mode 1 or the REST API tokenisation endpoint) and Zenith returns a token. 2. **Charge the token on your schedule.** Each scheduled charge is a normal payment request using the stored token — Zenith processes it as a new transaction and returns the usual result via callback, webhook, and API. The merchant is responsible for running the schedule. Zenith does not manage subscription cadence, trial periods, or plan logic — those live in your billing system. #### Payment methods for recurring[​](#payment-methods-for-recurring "Direct link to Payment methods for recurring") ##### Card tokenisation[​](#card-tokenisation "Direct link to Card tokenisation") Card-on-file recurring charges are the most common pattern. Tokenise the card once via Hosted Checkout Mode 1 or the REST API, then charge the token on your schedule. Scheme rules require the first charge to be customer-initiated — subsequent charges are merchant-initiated transactions (MIT) which Zenith flags appropriately to the card networks. ##### PayTo mandates[​](#payto-mandates "Direct link to PayTo mandates") PayTo supports recurring charges via the stored mandate. Unlike card tokenisation, PayTo mandates can be paused or cancelled by the customer in their banking app at any time. Your recurring billing loop must handle mandate state changes by subscribing to the webhook and checking `payToStatus` before each scheduled charge. See [Payment Methods → PayTo](/docs/resources/payment-methods/payto.md) for mandate lifecycle details. ##### CML charges[​](#cml-charges "Direct link to CML charges") If the customer has a CML entity with a payment method stored with Zenith, you can use their `customerReference` to take payments via the `/v2/payments` API. #### Handling failed recurring charges[​](#handling-failed-recurring-charges "Direct link to Handling failed recurring charges") Declined recurring payments are routine due to events like expired cards, insufficient funds or paused mandates. Your system should: * Detect decline reasons from the callback or API response * Apply a retry policy appropriate for the decline type (immediate retry for soft declines, deferred retry for insufficient funds, no retry for hard declines) * Notify the customer when retries are exhausted and ask them to update their payment method * Pause the subscription until a new token is captured * Accept unexpected error messages, which may change from time to time #### Merchant responsibilities[​](#merchant-responsibilities "Direct link to Merchant responsibilities") * Maintain the schedule and trigger each charge on time * Handle decline retries in your billing system * Track mandate/token state via webhooks and periodic API checks * Communicate with customers about upcoming charges, failures, and payment method updates * Stay compliant with scheme rules for card-on-file and mandate rules for PayTo #### Related[​](#related "Direct link to Related") * [Payment Methods → Cards](/docs/resources/payment-methods/cards.md) * [Payment Methods → PayTo](/docs/resources/payment-methods/payto.md) * [Hosted Checkout](/docs/integration-options/hosted-checkout.md) — tokenisation via Mode 1 * [REST API](/docs/integration-options/rest-api.md) * [Webhooks](/docs/resources/webhooks.md) --- ### TravelPay B2B Guide This can be a complex integration to build due to the need to send a customer in and out of our portal. Please contact us prior to building any TravelPay B2B integrations. If you are a platform facilitating an agent paying multiple suppliers, you will need to use our /v3/customers endpoint. If you are a supplier, there are a couple of options, likely using the methodology below, but please contact us to discuss your requirements. #### Overview[​](#overview "Direct link to Overview") This integration is designed for Customers (Travel Agents) to make payments to a Merchant(Travel Supplier) via Travel supplier's application/website. #### Customer(Travel Agent) Setup[​](#customertravel-agent-setup "Direct link to Customer(Travel Agent) Setup") * Travel agent logs into Travel Supplier platform, they add a bank account to wallet * When wallet is setup within Travel supplier's platform, the platform makes a POST call to api.travelpay.com.au/v2/customers to create a new customer. * Bank account details are provided in the payload. * Customer Reference should be a value that uniquely identifies the customer (Travel Agent) to the Travel Supplier ##### Email address parameter[​](#email-address-parameter "Direct link to Email address parameter") Within the TravelPay B2B platform, a customer profile can be linked to multiple merchants. TravelPay B2B platform allows the customers (Travel Agents) to have multiple email addresses associated with a customer profile with different access user rights. However, there can only be one customer profile owner. Customer profile owner email address is the key that links customer profiles between Travel supplier's platform and TravelPay B2B platform. If same email address is used during the setup process with both the Travel supplier's platform and TravelPay B2B platform, then passing this email address will link profiles together. ##### During the customer creation process[​](#during-the-customer-creation-process "Direct link to During the customer creation process") * If the supplied value for the email address parameter has a match in the TravelPay B2B platform, then the API will create new merchant customer link. New merchant customer link will be visible on the customer portal under my supplier's section. * If the supplied value for the email address parameter does not have a match in the TravelPay B2B platform, then the API will create a new customer profile. This will trigger a welcome email address to the email address so that the user can setup their TravelPay B2B customer portal. ##### Initial Payment[​](#initial-payment "Direct link to Initial Payment") * Travel Agent clicks a pay button within Travel supplier's platform. * Travel supplier's platform makes a POST call to api.travelpay.com.au/v2/payments * Customer Reference is used within the payload to match payment with the customer * Additional Reference is used for Booking information ##### After Payment is submitted[​](#after-payment-is-submitted "Direct link to After Payment is submitted") A routine has to be written to check the status of payment. As bank payments are not instant, at first paymentStatus of the payment will be Pending. This will change as the payment progresses. Alternatively, there are webhooks available which will be sent out once the payment is completed. #### How to update bank account details[​](#how-to-update-bank-account-details "Direct link to How to update bank account details") If Travel supplier needs to make an update to an existing customers bank account. Following process can be used. `GET api.travelpay.com.au/v2/customers/\{customerReference\}/account` to retrieve existing bank account details. `PUT api.travelpay.com.au/v2/customers/\{customerReference\}/account` to update existing bank account details. #### Flow Diagram[​](#flow-diagram "Direct link to Flow Diagram") --- ## Integration Options ### Integration Options ZenPay offers three integration paths. Choose based on how your customers reach checkout and how much control you want. | Path | Best for | Start here | | ------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | **Hosted Checkout** | Launching ZenPay checkout from your site or app via the JavaScript Plugin. | [Hosted Checkout](/docs/integration-options/hosted-checkout.md) | | **Payment Links** | Sharing a hosted payment URL with customers — no integration required. | [Payment Links](/docs/integration-options/payment-links.md) | | **REST API** | Backend-driven server-to-server operations like payments, refunds, tokens, sessions. | [REST API](/docs/integration-options/rest-api.md) | For detailed decision guidance, see [Choose Your Integration](/docs/get-started/choose-your-integration.md). --- ### Hosted Checkout Hosted Checkout is ZenPay's integrated checkout solution. Your frontend initialises the JavaScript Plugin (`zpPayment(...)`) using values prepared by your backend, then launches the ZenPay-hosted payment experience either in a modal iframe or via full-page redirect. * the plugin is the **launcher** * the hosted checkout page is the **payment UI** * your backend is the **source of trust** ![Payment plugin demo](/assets/images/demo-plugin-d672468623160b57226d1806ae3c478b.webp) *** #### What's in this section[​](#whats-in-this-section "Direct link to What's in this section") ##### [Hosted Checkout Pathway](/docs/integration-options/hosted-checkout/hosted-checkout-pathway.md)[​](#hosted-checkout-pathway "Direct link to hosted-checkout-pathway") What Hosted Checkout is, the payment journey, and the trust model. ##### [Building the Payload](/docs/integration-options/hosted-checkout/building-payload.md)[​](#building-payload "Direct link to building-payload") Configuration choices through generating the fingerprint. ##### [Input and Output Parameters](/docs/integration-options/hosted-checkout/input-output-parameters.md)[​](#input-output-parameters "Direct link to input-output-parameters") Input and output parameter reference tables. ##### [Full Worked Example](/docs/integration-options/hosted-checkout/full-worked-example.md)[​](#full-worked-example "Direct link to full-worked-example") Complete backend and frontend example, with a link to the live sandbox. ##### [Configuring Payment Types](/docs/integration-options/hosted-checkout/configuring-payment-types.md)[​](#configuring-payment-types "Direct link to configuring-payment-types") Payment method configuration — Cards, PayTo, Apple Pay, and more. ##### [Callbacks and Handling the Customer's Return](/docs/integration-options/hosted-checkout/callbacks.md)[​](#callbacks "Direct link to callbacks") Callbacks, payload reference, callback validation, and handling the customer's return. ##### [Plugin Errors and Troubleshooting](/docs/integration-options/hosted-checkout/plugin-troubleshooting.md)[​](#plugin-troubleshooting "Direct link to plugin-troubleshooting") Troubleshooting checklist, error codes, and common error codes. ##### [Best Practices / Hardening Your Integration](/docs/integration-options/hosted-checkout/best-practices.md)[​](#best-practices "Direct link to best-practices") Best practices for hardening your integration. ##### [Playground](/playground)[​](#playground "Direct link to playground") Interactive test page — experiment with plugin options without building a full integration first. *** #### Related[​](#related "Direct link to Related") * **Payment Links** → hosted link-based payments (no integration required) * **REST API** → backend-only payment operations * **Developer Tools** → debugging and validation tools * **Payment Methods** → [what each method is and where it's supported](/docs/resources/payment-methods.md) --- ### Best Practices / Hardening Your Integration #### Best Practices / Hardening Your Integration[​](#best-practices "Direct link to Best Practices / Hardening Your Integration") ##### Bot and fraud protection[​](#bot-and-fraud-protection "Direct link to Bot and fraud protection") ZenPay provides its own security measures, but you should also protect your own site. The most effective deterrent against automated attacks is an invisible challenge-response system such as Cloudflare Turnstile or Google reCAPTCHA v3. Require a valid token from these services before calling `zpPayment(...)` so only legitimate users can trigger a transaction. ##### CSRF protection[​](#csrf-protection "Direct link to CSRF protection") Accompany every payment initiation request with a unique, cryptographically strong CSRF token generated by your server. Never trust client-side data alone — validate transaction details on your backend before handing them to the plugin. Combine this with a strict Content Security Policy (CSP) that restricts which domains can execute scripts on your page. ##### Recap: fields to treat as mandatory[​](#recap-fields-to-treat-as-mandatory "Direct link to Recap: fields to treat as mandatory") `customerName`, `customerEmail`, `merchantUniquePaymentId` — technically optional for backwards compatibility, but should be required in all new integrations (see [Building the Payload](/docs/integration-options/hosted-checkout/building-payload.md#building-the-payload)). ##### Recap: fingerprint timing[​](#recap-fingerprint-timing "Direct link to Recap: fingerprint timing") Generate the fingerprint on button press, not page load, to avoid `E08`/`E03` expiry errors (see [Generating the Fingerprint](/docs/integration-options/hosted-checkout/building-payload.md#generating-the-fingerprint)). --- ### Building the Payload #### Configuration Choices Before You Build the Payload[​](#configuration-choices "Direct link to Configuration Choices Before You Build the Payload") ##### Display modes[​](#display-modes "Direct link to 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[​](#operating-modes "Direct link to 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[​](#plugin-methods "Direct link to 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[​](#building-the-payload "Direct link to 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. ```javascript 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[​](#generating-the-fingerprint "Direct link to Generating the Fingerprint") The `fingerprint` parameter is a **SHA3-512** hash of 7 pipe-separated fields, generated **server-side only**: ```text 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. --- ### Callbacks and Handling the Customer's Return #### Handling the Customer's Return[​](#handling-the-return "Direct link to Handling the Customer's Return") Your return page should use this trust order: 1. Verified callback state 2. Local server-side payment attempt state 3. Redirect parameters only as secondary UX context | State | Show | | ------------------------------------------------ | ---------------------------------------------- | | Redirect says success, callback not yet verified | Payment is being confirmed | | Callback verified success | Payment successful | | Callback verified failed | Payment failed | | Callback validation failed | Safe failure message — do not trust the result | **Do not rely on redirect alone to mark a payment as complete.** *** #### Callbacks — What They Are and Why They Matter[​](#callbacks-overview "Direct link to Callbacks — What They Are and Why They Matter") When a `callbackUrl` parameter is included in the plugin payload, Zenith Payments POSTs the transaction result to that URL after payment is processed. Callbacks are the authoritative server-side confirmation path for Hosted Checkout. Redirect is for customer-facing UX; callback validation is what allows your backend to trust the result. Unlike redirect, a callback: * Does not depend on the browser completing the journey * Is not controlled by the user * Includes a `validationCode` that can be verified server-side **Requirements:** * Transaction-specific — applies only to the transaction in which `callbackUrl` was supplied * Asynchronous — delivery happens in the background after Zenith finishes processing * Integrator-controlled — you decide the destination via `callbackUrl` * Not merchant-wide — does not notify on unrelated transactions (use Webhooks for broader patterns) * HTTPS POST endpoint — must be a secure endpoint reachable from Zenith Payments * Backend-owned — receive and validate on your backend, not your frontend * Validation required — validate `validationCode` before trusting the payload ##### Callback vs Redirect[​](#callback-vs-redirect "Direct link to Callback vs Redirect") | | Redirect | Callback | | ----------- | -------------------------- | -------------------------- | | Channel | Browser | Server-to-server | | Timing | Synchronous with browser | Asynchronous | | Reliability | Not guaranteed to complete | More reliable | | Purpose | Customer-facing UX | Authoritative confirmation | | Verified | No | Yes — via `validationCode` | For merchant-wide, event-style notifications across broader activity (not transaction-specific), see [Webhooks](/docs/resources/webhooks.md) instead. *** #### Callback Payload Reference[​](#callback-payload-reference "Direct link to Callback Payload Reference") | Field | Type | Notes | | ---------------------------- | ------- | ---------------------------------------------------- | | `paymentReference` | string | Unique payment reference assigned by Zenith | | `customerName` | string | Name of the customer | | `customerReference` | string | Reference provided by the merchant | | `paymentStatus` | number | Numeric status code of the payment | | `paymentStatusString` | string | Human-readable payment status | | `baseAmount` | number | Base transaction amount before fees | | `fundsToMerchant` | number | Net amount payable to the merchant | | `accountOrCardNo` | string | Masked account or card number | | `paymentAccount` | string | Payment account type such as Card or Bank | | `processingDate` | string | UTC ISO-8601 datetime | | `settlementDate` | string | UTC ISO-8601 datetime | | `processorReference` | string | Reference from the processor or gateway | | `isPaymentSettledToMerchant` | boolean | Whether the payment has been settled to the merchant | | `failureCode` | string | Failure code if unsuccessful, otherwise empty | | `failureReason` | string | Failure reason if unsuccessful, otherwise empty | | `paymentCard` | string | Card brand such as MasterCard or Visa | | `merchantUniquePaymentId` | string | Unique ID supplied by the merchant for the payment | | `merchantCode` | string | Merchant identifier code | | `transactionSource` | number | Numeric identifier for the source channel | | `transactionSourceString` | string | Human-readable source channel | | `customerFee` | number | Fee charged to the customer | | `processedAmount` | number | Total processed amount including fees | | `cardCategory` | string | Category of card such as Domestic or International | | `cardInformationSaved` | boolean | Whether card information was stored for tokenisation | | `validationCode` | string | SHA3-512 hash used to validate callback integrity | *Example payload structure (illustrative values only):* ```json { "response": { "paymentReference": "95408", "customerName": "Leah Adria", "customerReference": "a12b1926-811f-411c-b10a-1b330cc50d3b", "paymentStatus": 3, "paymentStatusString": "Successful", "baseAmount": 635.72, "fundsToMerchant": 635.72, "accountOrCardNo": "555555XXXXXX4444", "paymentAccount": "Card", "processingDate": "2025-08-27T21:48:59.447", "settlementDate": "2025-08-29T00:00:00", "processorReference": "ddb3a3436cbc7d77c241", "isPaymentSettledToMerchant": false, "failureCode": "", "failureReason": "", "paymentCard": "MasterCard", "merchantUniquePaymentId": "35917c6c-ee6b-4e52-866b-bea51841e796", "merchantCode": "1337", "transactionSource": 36, "transactionSourceString": "Public_Customer_OnlineOneOffPayment", "customerFee": 63.57, "processedAmount": 699.29, "cardCategory": "International Cards", "cardInformationSaved": false }, "validationCode": "1dbe5ddcc72b8207e839da42308d0596cbbb72e5bf7074520ec885e3c615bb519848fce4a0c073a9a7e6544854338cab9c0c87bc8c82c54bb3706a91c21a7410" } ``` *** #### Validating the Callback[​](#validating-the-callback "Direct link to Validating the Callback") The `validationCode` is a SHA3-512 hash of 7 pipe-separated fields, in exact order: ```text apiKey|userName|password|mode|paymentAmount|merchantUniquePaymentId|reference ``` * The first 6 fields are the **same values used in the original fingerprint hash** * Only the last field changes — from `timestamp` (fingerprint) to the returned transaction `reference` (validation code) * `reference` depends on mode — for Mode 1 (Tokenise), this is the `Token` output parameter ##### Reference field and amount format by mode[​](#reference-field-and-amount-format-by-mode "Direct link to Reference field and amount format by mode") | Mode | Reference field | Amount in hash | | -------------------- | ------------------ | -------------------- | | 0 — Make Payment | `paymentReference` | whole cents | | 1 — Tokenise | `token` | whole cents | | 2 — Custom Payment | `paymentReference` | `"0"` (literal zero) | | 3 — Preauthorisation | `preauthReference` | whole cents | > **Mode 3 note:** Preauthorisation callbacks carry `preauthStatus` and `preauthReference` in place of `paymentStatus` and `paymentReference`. **Steps to validate:** 1. Receive the callback payload 2. Extract `merchantUniquePaymentId`, the returned reference, and `validationCode` 3. Rebuild the input string in the exact order above 4. Generate SHA3-512 server-side 5. Compare your computed value against the received `validationCode` If they match, the callback is authentic — update payment state. If they don't match, reject the callback, do not trust the result, and log for investigation. ##### Recovering launch context[​](#recovering-launch-context "Direct link to Recovering launch context") To verify a callback you need the original `mode`, `paymentAmount`, and `merchantUniquePaymentId` from the launch — none of which Zenith echoes back reliably across all modes (Tokenise callbacks omit `merchantUniquePaymentId`). The stateless approach is a **signed callback token**: embed a short-lived signed token in the `callbackUrl` as a query parameter (e.g. `?t=…`). The token carries the launch context and is verified by your server before the `validationCode` check runs. This avoids any session store or database lookup: ```text callbackUrl: https://your-server/callbacks/zenith?t= ``` ##### Backend handling checklist[​](#backend-handling-checklist "Direct link to Backend handling checklist") * Accept POST requests over HTTPS * Validate `validationCode` before trusting any field * Process callbacks idempotently * Update local payment state safely * Log failures and mismatches clearly **Do not** trust callback data without validation. **Do not** rely on redirect as final truth. **Do not** expose credentials or validation logic to the browser. ##### Timing and idempotency[​](#timing-and-idempotency "Direct link to Timing and idempotency") Callbacks can arrive before redirect completes, after redirect completes, without redirect completing, or more than once. * Treat callbacks as idempotent * Use `merchantUniquePaymentId` to prevent double-processing * Show a pending / confirming state if redirect returns before callback validation completes --- ### Configuring Payment Types #### Payment Method Configuration[​](#payment-method-configuration "Direct link to Payment Method Configuration") For conceptual information about what each method is and where it's supported, see the Payment Methods page. This section covers plugin-specific setup only. ##### Cards[​](#cards "Direct link to Cards") Supported in all modes (0, 1, 2, 3) — see [Configuration Choices](/docs/integration-options/hosted-checkout/building-payload.md#configuration-choices) for what each mode does. For tokenisation (Mode 1): launch the plugin in Mode 1 to capture a card and receive a token via redirect and callback. The token can then be charged later through your normal payment flow or via the REST API. For backend-led tokenisation without launching the plugin, use `POST /v2/cardproxies` instead. ##### Bank / PayID[​](#bank-payid "Direct link to Bank / PayID") Bank one-off payments and PayID are supported **only on Hosted Checkout** and are considered legacy flows — most real-time bank scenarios now use PayTo instead. See Payment Methods → Bank / PayID for program levels and reconciliation detail. ##### PayTo[​](#payto "Direct link to PayTo") Available through the plugin for both tokenisation and one-off payments. * **Enable:** pass `allowPayToOneOffPayment: true` when loading the plugin * **Tokenisation:** launch in Mode 1; customer enters bank details, plugin returns a `Pending` token via redirect + callback. Customer approves the mandate in their bank app, at which point the token becomes `Active` * **Display:** flag newly-created PayTo tokens as "Pending Mandate Approval" in your wallet UI until approved * **Status updates:** subscribe to the Zenith Customer Webhook for mandate approval/decline/cancellation events, or poll `GET /v2/proxies/{token}` for current status * **Charging:** once `Active`, pass the token like any other card or bank token — no plugin-side change needed See Payment Methods → PayTo for the mandate lifecycle, webhook payload shape, and status field details. ##### Apple Pay[​](#apple-pay "Direct link to Apple Pay") Requires a domain verification file before it can be enabled on your site: 1. Contact the Zenith Payments Integrations Team with the domain URL that hosts the plugin (e.g. `www.zenpay.com.au`) 2. Zenith provides a verification file to place at `/.well-known/apple-developer-merchantid-domain-association` on that domain 3. Once you confirm the upload, Zenith registers the domain with Apple Pay > This step is only required when you host the plugin on your own domain. Payment Links are fully Zenith-hosted and do not require it. The Apple Pay button currently shows only on Apple devices; a QR code fallback for non-Apple devices is planned. ##### Google Pay and Alipay+[​](#google-pay-alipay "Direct link to Google Pay and Alipay+") See Payment Methods → Digital Wallets for availability and plugin setup details. ##### BNPL / SlicePay[​](#bnpl-slicepay "Direct link to BNPL / SlicePay") **TravelPay merchants only.** SlicePay is only available to TravelPay merchants — speak to your BDM about enabling this method. Once enabled on the merchant account, it appears as a payment option with no additional plugin parameter needed beyond the normal Mode 0 flow. See Payment Methods → Buy Now Pay Later for product detail. --- ### Full Worked Example #### Full Worked Example[​](#full-worked-example "Direct link to Full Worked Example") Every file below is the exact source that runs in the [live sandbox](/webpod) — not a transcription of it. Open the sandbox to run this same code against the ZenPay sandbox environment and watch the callback arrive. The split follows the [trust model](/docs/integration-options/hosted-checkout/hosted-checkout-pathway.md#trust-model): the backend holds the credentials and signs; the browser only launches what it was handed. Credentials The sandbox reads its merchant credentials from `WCDEMO_*` environment variables — that prefix is specific to the demo. Use whatever names your own configuration uses; what matters is that they are read **server-side** and never reach the browser. ##### Backend — sign the request[​](#backend-authorise "Direct link to Backend — sign the request") Mints the `timestamp`, `merchantUniquePaymentId` and SHA3-512 `fingerprint`, then returns a payload the browser can safely receive. `username` and `password` are used only to compute the hash and are never part of the response. server/routes/authorise.v3.ts ```ts /** * @fileoverview Server-side authorisation route for Hosted Checkout (standalone / zero-SDK). * Mints the timestamp, MUPID and SHA3-512 fingerprint directly via `\@noble/hashes` — no SDK package — and returns the signed payload `$.zpPayment(...)` needs to launch. */ import { sha3_512 } from '@noble/hashes/sha3.js'; import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js'; import { zValidator } from '@hono/zod-validator'; import { Hono } from 'hono'; import { z } from 'zod'; import { mintCallbackToken, mintStreamToken } from '../demo-tokens.ts'; /** Merchant signing credentials — sandbox demo only, never production. */ const apiKey: string = process.env.WCDEMO_API_KEY ?? 'Your-Key'; const username: string = process.env.WCDEMO_USERNAME ?? 'Your-Username'; const password: string = process.env.WCDEMO_PASSWORD ?? 'Your-Password'; const merchantCode: string = process.env.WCDEMO_MERCHANTCODE ?? 'Your-Merchant-Code'; const sid: string = process.env.WCDEMO_SESSION_ID ?? ''; const callbackApiUrl: string = `${process.env.WCDEMO_API_ORIGIN ?? 'https://api.zenithpayments.support'}/v1/docs/webpod/callbacks`; const authoriseBodySchema = z.object({ paymentAmount: z.number().positive('payment amount must be greater than zero'), customerName: z.string().trim().min(1), customerEmail: z.email(), customerReference: z.string().trim().min(1), }); type AuthoriseCheckoutRequest = z.infer; /** Generates a UTC timestamp in the ISO 8601 format required by ZenPay (`YYYY-MM-DDTHH:MM:SS`). */ const zpTimestamp = (): string => new Date().toISOString().slice(0, 19); /** Generates a random, URL-safe Merchant Unique Payment ID (MUPID) — same algorithm as `@zp-hcp/shared`'s `createZpMupid()`, inlined here so this route stays SDK-free. */ const zpMupid = (): string => { const bytes = crypto.getRandomValues(new Uint8Array(16)); let binary = ''; for (const byte of bytes) { binary += String.fromCharCode(byte); } return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/[=]+$/, ''); }; /** * Converts a dollar amount into whole cents as a string for fingerprint hashing. * * Mode 0 only. The `mode` this feeds is the hardcoded `0` below, and `x 100` is * the right answer only for that mode — modes 1 and 2 hash `"0"` regardless of * the amount. `resolveZpHashAmount` in `@zp-hcp/shared` owns all four rules but * cannot be imported here: this file is mounted into the Nodepod sandbox and run * through its regex TypeScript stripper, so it stays SDK-free like `zpMupid`. */ const zpAmountToCents = (amountDollars: number): string => Math.round(amountDollars * 100).toString(); /** * Calculates the SHA3-512 fingerprint hash for a payment request. * Hashes seven pipe-separated fields in fixed order: * `apiKey|username|password|mode|paymentAmountInCents|merchantUniquePaymentId|timestamp`. * @param apiKey - Merchant API key. * @param username - Merchant username. * @param password - Merchant password. * @param mode - Plugin mode (`0` for Make Payment). * @param paymentAmount - Payment amount in dollars. * @param merchantUniquePaymentId - Unique merchant transaction ID. * @param timestamp - ISO UTC timestamp (`YYYY-MM-DDTHH:MM:SS`). * @returns 128-character lowercase hexadecimal SHA3-512 digest. */ export function zpFingerprint(apiKey: string, username: string, password: string, mode: number, paymentAmount: number, merchantUniquePaymentId: string, timestamp: string): string { const amountCents: string = zpAmountToCents(paymentAmount); const source: string = [apiKey, username, password, String(mode), amountCents, merchantUniquePaymentId, timestamp].join('|'); return bytesToHex(sha3_512(utf8ToBytes(source))); } /** Inputs for {@link buildZpV3AuthoriseRequest}. */ interface BuildAuthoriseInput { baseUrl: string; request: AuthoriseCheckoutRequest; } /** Payload returned to launch Hosted Checkout. */ interface ZpV3AuthorisePayload { url: string; apiKey: string; fingerprint: string; merchantCode: string; timestamp: string; merchantUniquePaymentId: string; customerEmail: string; redirectUrl: string; callbackUrl: string; mode: number; paymentAmount: number; customerName: string; customerReference: string; allowApplePayOneOffPayment: boolean; allowGooglePayOneOffPayment: boolean; allowSaveCardInformation: boolean; allowUnionPayOneOffPayment: boolean; allowAliPayPlusOneOffPayment: boolean; allowBankAcOneOffPayment: boolean; allowPayToOneOffPayment: boolean; allowPayIdOneOffPayment: boolean; allowLatitudePayOneOffPayment: boolean; allowSlicePayOneOffPayment: boolean; allowCardOneOffPayment: boolean; allowCardTokenisePayment: boolean; allowWeChatOneOffPayment: boolean; } /** * Constructs the signed authorisation payload for a payment integration. * @param input - Base URL and parsed checkout request fields. * @returns Authorisation options object for Hosted Checkout. */ function buildZpV3AuthoriseRequest(input: BuildAuthoriseInput): ZpV3AuthorisePayload { const { baseUrl, request } = input; const { paymentAmount, customerEmail, customerName, customerReference } = request; const timestamp: string = zpTimestamp(); const merchantUniquePaymentId: string = zpMupid(); const mode: number = 0; const fingerprint: string = zpFingerprint(apiKey, username, password, mode, paymentAmount, merchantUniquePaymentId, timestamp); const callbackToken: string = mintCallbackToken(paymentAmount, merchantUniquePaymentId, timestamp, 'webpod-v3'); const streamToken: string = mintStreamToken(paymentAmount, merchantUniquePaymentId, timestamp); const payload: ZpV3AuthorisePayload = { url: 'https://pay.sandbox.travelpay.com.au/online/v5', apiKey, fingerprint, merchantCode, timestamp, merchantUniquePaymentId, customerEmail, redirectUrl: `${baseUrl}/webpod/result?t=${encodeURIComponent(streamToken)}&sid=${encodeURIComponent(sid)}`, callbackUrl: `${callbackApiUrl}?t=${encodeURIComponent(callbackToken)}&sid=${encodeURIComponent(sid)}`, mode, paymentAmount, customerName, customerReference, allowApplePayOneOffPayment: true, allowGooglePayOneOffPayment: true, allowSaveCardInformation: true, allowUnionPayOneOffPayment: true, allowAliPayPlusOneOffPayment: true, allowPayToOneOffPayment: true, allowBankAcOneOffPayment: false, allowPayIdOneOffPayment: false, allowLatitudePayOneOffPayment: false, allowSlicePayOneOffPayment: false, allowCardOneOffPayment: true, allowCardTokenisePayment: true, allowWeChatOneOffPayment: true, }; return payload; } /** Hono routes for checkout authorise. */ export const authoriseRoutes: Hono = new Hono(); authoriseRoutes.post( '/v1/checkout/authorise', zValidator('json', authoriseBodySchema, (result, c) => { if (!result.success) { return c.json({ error: result.error.issues[0]?.message ?? 'invalid request' }, 400); } return undefined; }), async (c): Promise => { try { const request: AuthoriseCheckoutRequest = c.req.valid('json'); const baseUrl: string = process.env.WCDEMO_BASE_URL ?? new URL(c.req.url).origin; const payload: ZpV3AuthorisePayload = buildZpV3AuthoriseRequest({ baseUrl, request }); return c.json(payload); } catch (error: unknown) { const message: string = error instanceof Error ? error.message : String(error); return c.json({ error: message }, 400); } } ); ``` ##### Backend — verify the callback[​](#backend-callback "Direct link to Backend — verify the callback") Recomputes the SHA3-512 `ValidationCode` from the callback body and compares it against the one ZenPay sent. Never update order or payment status until this returns a match. server/routes/callback.v3.ts ```ts /** * @fileoverview Server-side callback verification route for Hosted Checkout (standalone / zero-SDK). * Parses the callback with Zod and recomputes the SHA3-512 `ValidationCode` directly — no SDK package — by hashing `apiKey|username|password|mode|paymentAmountInCents|merchantUniquePaymentId|reference` (`reference` is `response.token`). Never update payment status until the recomputed hash matches the callback's. */ import { sha3_512 } from '@noble/hashes/sha3.js'; import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js'; import { zValidator } from '@hono/zod-validator'; import { Hono } from 'hono'; import type { Context } from 'hono'; import { z } from 'zod'; /** Merchant credentials used for callback signature verification. */ const apiKey: string = process.env.WCDEMO_API_KEY ?? 'Your-Key'; const username: string = process.env.WCDEMO_USERNAME ?? 'Your-Username'; const password: string = process.env.WCDEMO_PASSWORD ?? 'Your-Password'; const callbackByMupid = new Map(); const callbackBodySchema = z.object({ merchantUniquePaymentId: z.string(), paymentAmount: z.number(), response: z.object({ responseCode: z.string().optional(), responseText: z.string().optional(), paymentStatus: z.number().optional(), paymentReference: z.string().optional(), token: z.string().optional(), validationCode: z.string().optional(), }), }); type CallbackBody = z.infer; /** * Converts a dollar amount into whole cents as a string for ValidationCode hashing. * * Mode 0 only. The `mode` this feeds is the hardcoded `0` below, and `x 100` is * the right answer only for that mode — modes 1 and 2 hash `"0"` regardless of * the amount. `resolveZpHashAmount` in `@zp-hcp/shared` owns all four rules but * cannot be imported here: this file is mounted into the Nodepod sandbox and run * through its regex TypeScript stripper, so it stays SDK-free like `zpMupid`. */ const zpAmountToCents = (amountDollars: number): string => Math.round(amountDollars * 100).toString(); /** Inputs for {@link verifyValidationCode}. */ interface VerifyValidationCodeInput { apiKey: string; username: string; password: string; mode: number; body: CallbackBody; } /** * Recomputes the SHA3-512 ValidationCode hash and verifies it against the callback payload. * @param input - Merchant credentials, plugin mode, and the parsed callback payload. * @returns True if the computed SHA3-512 hash matches `body.response.validationCode`. */ function verifyValidationCode(input: VerifyValidationCodeInput): boolean { const { apiKey, username, password, mode, body } = input; const { validationCode, token } = body.response; if (!validationCode) { return false; } const amountCents: string = zpAmountToCents(body.paymentAmount); const reference: string = token ?? ''; const source: string = [apiKey, username, password, String(mode), amountCents, body.merchantUniquePaymentId, reference].join('|'); const computedHash: string = bytesToHex(sha3_512(utf8ToBytes(source))); return computedHash.toLowerCase() === validationCode.toLowerCase(); } /** Payment status 0 indicates a successful payment in ZenPay Hosted Checkout. */ function isPaymentSuccessful(status: number | undefined): boolean { return status === 0; } /** Hono routes for ZenPay callback verification. */ export const callbackRoutes: Hono = new Hono(); callbackRoutes.post( '/v1/callback/zenith', zValidator('json', callbackBodySchema, (result, c) => { if (!result.success) { return c.json({ error: 'malformed payment callback' }, 400); } return undefined; }), async (c): Promise => { try { const body: CallbackBody = c.req.valid('json'); const mode: number = 0; const isValid: boolean = verifyValidationCode({ apiKey, username, password, mode, body }); const successful: boolean = isValid && isPaymentSuccessful(body.response.paymentStatus); const result = { received: true, valid: isValid, successful, paymentReference: body.response.paymentReference, }; callbackByMupid.set(body.merchantUniquePaymentId, result); return c.json(result); } catch (error: unknown) { const message: string = error instanceof Error ? error.message : String(error); return c.json({ error: message }, 400); } } ); callbackRoutes.get('/v1/callback/zenith/status', (c: Context): Response => { const mupid: string = c.req.query('mupid') ?? ''; return c.json(callbackByMupid.get(mupid) ?? null); }); ``` ##### Frontend — v3, CDN / no build step[​](#frontend-v3 "Direct link to Frontend — v3, CDN / no build step") The jQuery + Bootstrap build, loaded from the CDN with no bundler. Calls the authorise endpoint above, then hands the signed payload straight to `$.zpPayment(...)`. index.html ```html Checkout ``` --- ### Hosted Checkout Pathway #### What Hosted Checkout Is[​](#what-hosted-checkout-is "Direct link to What Hosted Checkout Is") Hosted Checkout is ZenPay's integrated checkout solution. Your frontend initialises the JavaScript Plugin (`zpPayment(...)`) using values prepared by your backend, then launches the ZenPay-hosted payment experience either in a modal iframe or via full-page redirect. * The plugin is the launcher * The hosted checkout page is the payment UI * Your backend is the source of trust **When to use Hosted Checkout:** * Your site or app needs to launch ZenPay checkout * You want ZenPay to host the payment UI and handle sensitive data * You want modal or redirect flexibility * You want your backend to remain responsible for trust and payment state Alternatively, * Use **Payment Links** instead when you want a hosted payment link without building an embedded integration. * Use the **REST API** when you need backend-only server-to-server payment operations. * Use **Developer Tools** when debugging fingerprints, return URLs, or validation issues. *** #### The Payment Journey (High-Level Flow)[​](#payment-journey "Direct link to The Payment Journey (High-Level Flow)") 1. Your frontend requests payment bootstrap data from your backend 2. Your backend generates the fingerprint and prepares the payment payload 3. Your backend returns safe bootstrap data to the frontend 4. Your frontend initialises `zpPayment(...)` and launches the plugin 5. The customer completes payment on the ZenPay-hosted UI 6. ZenPay redirects the customer back to your site 7. ZenPay optionally sends a server-to-server callback 8. Your backend validates the callback before confirming the result ![Hosted Checkout Journey](/assets/images/payment_checkout_consolidated_flow-fcaf6a93ecf7e2bd13fc8d48c8416a29.png) *** #### Trust Model — Who's Responsible for What[​](#trust-model "Direct link to Trust Model — Who's Responsible for What") Understanding this split up front makes every later section make sense — it's the reasoning behind the fingerprint, the payload, and the callback validation. **Browser responsibilities — the browser should:** * Request bootstrap data from your backend * Initialise `zpPayment(...)` * Launch the payment flow * Show pending, success, failed, or cancelled UI states * Handle return-page UX **The browser must not:** * Generate the fingerprint * Contain merchant secrets * Verify the callback * Treat redirect query parameters as the only source of truth **Backend responsibilities — your backend should:** * Hold ZenPay credentials securely * Generate the fingerprint server-side * Create a fresh `merchantUniquePaymentId` and `timestamp` per attempt * Receive and validate callbacks * Update local payment state * Return authoritative payment status to the frontend --- ### Input and Output Parameters #### Input Parameters[​](#input-parameters "Direct link to Input Parameters") Mode0 - Make Payment 49results Search... Loading…
Fingerprint Hash Composition The `fingerprint` parameter is a **SHA3-512** hash of 7 pipe-separated fields. All credentials are **case-sensitive**. Hover over each field for details: apiKey API Key Public API key (GUID) provided by Zenith. Case-sensitive. First field in the pipe-separated hash input. |username Username Integration username provided by Zenith. Case-sensitive. Used in the fingerprint hash but never sent to the client or included in the URL. |password Password Integration password provided by Zenith. Case-sensitive. Used in the fingerprint hash but never sent to the client or included in the URL. |mode Mode 0 = Make Payment, 1 = Tokenise, 2 = Custom Payment (amount in hash must be 0, actual amount in payload), 3 = Pre-authorisation. |amount Amount (dollars) Payment amount in dollars, exactly as the plugin payload carries it (49.90, 123, 123.1). The hash uses the same amount in whole cents with no decimal point — 49.90 becomes 4990 and 123.1 becomes 12310. Mode 2 always hashes 0. |merchantUniquePaymentId Merchant Unique Payment ID Your unique transaction identifier. Must be unique per attempt — reusing a previous ID with the same timestamp triggers error E03. |timestamp Timestamp (UTC) UTC format: YYYY-MM-DDTHH:mm:ss (no timezone suffix, no milliseconds). Must match exactly between hash and plugin payload. Server allows 90-second skew. * `paymentAmount` must be in **cents** (e.g. $150.53 = `15053`). For Mode 2, always pass `0`. * `timestamp` must be in **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:** Use the [Fingerprint Generator](/tools/generator) or [Fingerprint Validator](/tools/validator) to test your implementation. *** #### Output Parameters[​](#output-parameters "Direct link to Output Parameters") Mode0 - Make Payment 33results Search... Loading…
Validation Code Composition The callback payload includes an additional `ValidationCode` parameter that you can use to **authenticate the callback** and verify it originated from Zenith Payments. The `ValidationCode` is a **SHA3-512** hash of 7 pipe-separated fields. All credentials are **case-sensitive**. Hover over each field for details: apiKey API Key Public API key (GUID) provided by Zenith. Same key used in the fingerprint hash. |userName Username Integration username provided by Zenith. Case-sensitive. Same credential used in the fingerprint hash. |password Password Integration password provided by Zenith. Case-sensitive. Same credential used in the fingerprint hash. |mode Mode 0 = Make Payment, 1 = Tokenise, 2 = Custom Payment, 3 = Pre-authorisation. Same value sent in the request. |paymentAmount Amount (cents) Payment amount in whole cents. Same value used in the fingerprint hash. |merchantUniquePaymentId Merchant Unique Payment ID Your unique transaction identifier. Same value sent in the request. |reference Reference The transaction reference returned in the callback response. For Mode 1 (Tokenise), this is the Token output parameter. * The first 6 fields are the **same values** used in the original fingerprint hash. * `reference` is the transaction reference returned in the callback — for Mode 1 (Tokenise), this is the **Token** output parameter. * To verify: regenerate the hash server-side using your credentials + the returned `reference`, and compare against the received `ValidationCode`. **See also:** [Callbacks and Validation](/docs/integration-options/hosted-checkout/callbacks.md#callbacks-overview) — full receive-and-verify flow --- ### Plugin Errors and Troubleshooting #### Troubleshooting Checklist[​](#troubleshooting-checklist "Direct link to Troubleshooting Checklist") If the plugin launch is not behaving as expected, check: * Frontend is calling your backend bootstrap endpoint * Backend is returning all required fields * `displayMode` is what you expect * Fingerprint was generated server-side * Timestamp format is correct (`YYYY-MM-DDTHH:mm:ss` UTC, no milliseconds) * `merchantUniquePaymentId` is fresh per attempt * `redirectUrl` and optional `callbackUrl` are correctly configured * You are not treating redirect alone as final payment success * You are using the correct Hosted Checkout Page URL for the environment *** #### Error Codes[​](#error-codes "Direct link to Error Codes") 20results Search... Loading… *** #### Common Error Codes[​](#common-error-codes "Direct link to Common Error Codes") ##### E08 — incorrect credentials or fingerprint[​](#e08--incorrect-credentials-or-fingerprint "Direct link to E08 — incorrect credentials or fingerprint") Common causes: * Wrong username, password, or `apiKey` — all are case-sensitive; check for trailing spaces * Wrong timestamp format — must be UTC `YYYY-MM-DDTHH:mm:ss`, no timezone suffix, no milliseconds * Amount in dollars instead of cents — the fingerprint uses cents ($100.50 → 10050) * Wrong hashing algorithm — must be SHA3-512, not SHA-256 or SHA-512 ##### E03 — expired fingerprint[​](#e03--expired-fingerprint "Direct link to E03 — expired fingerprint") Fingerprint expired (15-minute window). See [Generating the Fingerprint](/docs/integration-options/hosted-checkout/building-payload.md#generating-the-fingerprint). ##### Other initialisation errors[​](#other-initialisation-errors "Direct link to Other initialisation errors") > "We have been unable to verify you. Please refresh the page, re-enter your payment account details, and submit the form again." Typically caused by a failed reCAPTCHA verification. Since reCAPTCHA is managed by Google, there are various reasons it may fail. Usually resolved by: * Refreshing the page and trying again * Clearing the browser cache and cookies * Opening the payment page in a private/incognito browser window * Trying a different browser or device This is generally a client-side issue, so one of the above steps will usually resolve it. ##### Other common error codes (upstream, not initialisation)[​](#other-common-error-codes-upstream-not-initialisation "Direct link to Other common error codes (upstream, not initialisation)") Most other errors originate from systems upstream of Zenith Payments and relate to the customer's card, bank, or financial institution — the primary exception being session timeout (payment sessions expire after **30 minutes**; once expired, the payment can no longer be processed). Common upstream scenarios: * **3DS validation errors** — the cardholder did not successfully complete identity verification with their bank or card issuer * **Insufficient funds** — the account does not have sufficient funds available * **Do Not Honour** — the bank has declined the transaction, e.g. for fraud prevention or suspicious activity * **Card validation errors** — incorrect card number, CVV, expiry date, or other security-related information * **2003 – Transaction Declined** — a generic bank decline code; the payer will usually need to contact their bank * **E206 – Refer to Customer** — typically indicates insufficient funds or that the account has exceeded transaction or payment limits There are many additional error codes depending on payment method and the customer's bank/issuer policies. See the [18-entry error code table](/docs/integration-options/hosted-checkout/plugin-troubleshooting.md#error-codes) above for the full list. **When to contact the financial institution:** when an error originates from the card scheme, bank, or payment issuer, Zenith Payments is often unable to determine the specific reason for the decline. Recommend the customer contact their financial institution's **Technical Support Team** specifically — frontline customer service reps often have limited visibility into transaction-level decline reasons. --- ### Payment Links Payment Links let merchants accept payments using a ZenPay-hosted payment link without building a custom checkout integration. This is the simplest ZenPay payment path. A merchant is given a hosted checkout page URL, shares that link with customers, and customers complete payment on the hosted page. Payment Links can be organised directly with you BDM and do not need consultation with the integrations team. Please reach out to your BDM for setup. ![Payment link demo](/assets/images/payment-link-demo-91fc23cdf3cbaf6089e25bda39570fce.webp) *** #### What this page covers[​](#what-this-page-covers "Direct link to What this page covers") This page explains: * what Payment Links are * when to use them * how they differ from Hosted Checkout * how the customer flow works * what merchants can usually configure * where to go next in this section *** #### What Payment Links are[​](#what-public-payment-pages-are "Direct link to What Payment Links are") A Payment Link is a ZenPay-hosted checkout page that is accessed directly by URL. Instead of loading the JavaScript Plugin from a merchant website and launching checkout from the merchant’s own frontend, the merchant uses a hosted payment link that customers open directly in the browser. This makes Payment Links a good fit for merchants who want a working payment page quickly and do not need a full embedded integration. *** #### Who this is for[​](#who-this-is-for "Direct link to Who this is for") Payment Links are best for: * merchants who want the quickest path to accepting payments * teams with low technical overhead * merchants who do not need embedded checkout * teams that prefer a hosted-link model over a custom integration This section can be useful for product managers, operations teams, onboarding teams, and merchants evaluating their options. *** #### When to use Payment Links[​](#when-to-use-public-payment-pages "Direct link to When to use Payment Links") Use Payment Links when the merchant wants: * a hosted payment link * a simple setup * little or no development effort * a payment page that can be shared directly with customers * a fast path to accepting payments Typical examples include: * merchants without a development team * merchants starting with a manual or semi-manual payment flow * invoice or payment-request style use cases * merchants who want to onboard quickly before considering a deeper integration *** #### When not to use Payment Links[​](#when-not-to-use-public-payment-pages "Direct link to When not to use Payment Links") Payment Links are not the right path when the merchant needs: * checkout launched from their own site or app * embedded modal / iframe checkout * redirect checkout controlled from their own frontend * application-managed checkout sessions * tighter control over the payment flow inside an existing cart, portal, or app journey In those cases, use **Hosted Checkout** instead. *** #### How Payment Links differ from Hosted Checkout[​](#how-public-payment-pages-differ-from-hosted-checkout "Direct link to How Payment Links differ from Hosted Checkout") ##### Payment Links[​](#payment-links "Direct link to Payment Links") With Payment Links: * the customer opens a hosted payment link directly * the merchant does not need to load the ZenPay JavaScript Plugin * the payment experience starts from the hosted page itself * the integration effort is low ##### Hosted Checkout[​](#hosted-checkout "Direct link to Hosted Checkout") With Hosted Checkout: * the merchant site or app launches ZenPay checkout * the merchant frontend uses the JavaScript Plugin * checkout is launched as modal / iframe or redirect * the integration is more flexible but requires implementation work A simple way to think about it is: * **Payment Links** = hosted link * **Hosted Checkout** = integrated launch from your own site/app *** #### How the customer flow works[​](#how-the-customer-flow-works "Direct link to How the customer flow works") At a high level, the Payment Links flow is: 1. The merchant is given a hosted checkout page link. 2. The merchant shares that link with the customer. 3. The customer opens the page in the browser. 4. The customer enters their details and payment information. 5. ZenPay processes the payment on the hosted page. 6. The merchant is informed of the result through the configured merchant-side process. This flow is designed to be simple and direct. *** #### Customer experience[​](#customer-experience "Direct link to Customer experience") From the customer’s perspective, Payment Links are a hosted payment form. The page shows: * the merchant’s logo (if configured) * customer detail fields * payment amount * supported payment methods * confirmation messaging after payment The page layout and fields are standard across all Payment Links. The merchant logo is the only brandable element. *** #### Merchant configuration[​](#merchant-configuration "Direct link to Merchant configuration") The only merchant-configurable element on a Payment Link is the **merchant logo** displayed on the page. All other aspects of the page — fields, layout, wording, and payment methods — are part of the standard ZenPay-hosted experience and are not editable by the merchant. See the **Setup & Branding** page for details on logo configuration. *** #### Notifications and payment outcomes[​](#notifications-and-payment-outcomes "Direct link to Notifications and payment outcomes") After a payment is made, the merchant needs a way to know what happened. Depending on setup, this may include: * email notifications * webhook notifications * portal/reporting visibility * internal reconciliation processes The details should be documented in the **Notifications** page. This overview page should simply explain that payment outcome handling exists and is part of the product setup. *** #### Related pages[​](#related-pages "Direct link to Related pages") After reading this page, the next pages in this section should be: * **Setup & Branding** * **Notifications** * **FAQ** If the reader needs integrated checkout instead, direct them to: * **Hosted Checkout** * **JavaScript Plugin** * **HCP Reference** *** #### Summary[​](#summary "Direct link to Summary") Payment Links are the simplest Zenith-hosted payment option. Use them when a merchant wants a hosted payment link that customers can open directly, without building a custom checkout integration. Use **Hosted Checkout** instead when the merchant needs checkout launched from their own website or application. --- ### FAQ This page answers common merchant questions about Payment Links. *** #### Do I need a developer to use Payment Links?[​](#do-i-need-a-developer-to-use-public-payment-pages "Direct link to Do I need a developer to use Payment Links?") Not always. Payment Links are intended for merchants who want a hosted payment option without building a full custom checkout integration. *** #### Can I share the payment link directly with customers?[​](#can-i-share-the-payment-link-directly-with-customers "Direct link to Can I share the payment link directly with customers?") Yes. The Payment Link is designed to be accessed directly by URL, so the merchant can share the link with customers. *** #### Can I brand the page?[​](#can-i-brand-the-page "Direct link to Can I brand the page?") The only brandable element is the **merchant logo**. All other page elements (layout, fields, wording) are part of the standard ZenPay-hosted experience and cannot be changed. *** #### What payment methods can appear on the page?[​](#what-payment-methods-can-appear-on-the-page "Direct link to What payment methods can appear on the page?") The payment methods shown on a Payment Link depend on merchant configuration. Depending on setup, this may include card payment, bank payment, and other hosted payment methods made available for that merchant. *** #### What customer information can be collected?[​](#what-customer-information-can-be-collected "Direct link to What customer information can be collected?") The hosted page includes standard fields such as customer name, customer email, contact number, payment amount, and customer reference. These fields are fixed and not configurable by the merchant. *** #### How do I know I have been paid?[​](#how-do-i-know-i-have-been-paid "Direct link to How do I know I have been paid?") The merchant receives the payment outcome through the configured merchant-side process. Depending on setup, this may include email notifications, webhook notifications, portal visibility, or merchant-side reconciliation. *** #### Can I use email or webhook notifications?[​](#can-i-use-email-or-webhook-notifications "Direct link to Can I use email or webhook notifications?") Yes, depending on merchant setup. Some merchants may rely on email notifications, while others may use webhook or callback notifications as part of a deeper internal workflow. *** #### When should I use Hosted Checkout instead?[​](#when-should-i-use-hosted-checkout-instead "Direct link to When should I use Hosted Checkout instead?") Use Hosted Checkout instead when the merchant needs checkout to be launched from their own website or application, or when the payment flow needs to be embedded into a broader order, cart, or session journey. *** #### Where should I go next?[​](#where-should-i-go-next "Direct link to Where should I go next?") If you are just getting started, read: * [Overview](/docs/integration-options/payment-links.md) * [Setup & Branding](/docs/integration-options/payment-links/setup-and-branding.md) * [Notifications](/docs/integration-options/payment-links/notifications.md) --- ### Notifications #### What this page covers[​](#what-this-page-covers "Direct link to What this page covers") This page explains: * how merchants can be informed about payment outcomes * what notification paths may be available * how notifications relate to reconciliation and follow-up workflows * when technical webhook detail should be handled in separate documentation *** #### Why notifications matter[​](#why-notifications-matter "Direct link to Why notifications matter") Once a customer completes payment on a hosted page, the merchant needs a clear way to understand what happened. For Payment Links, that may include: * confirming that a payment was successful * knowing when a payment failed * identifying when operational follow-up is needed * supporting merchant-side reconciliation *** #### Possible notification paths[​](#possible-notification-paths "Direct link to Possible notification paths") Depending on merchant setup, payment outcomes may be communicated through: * email notifications * webhook notifications * merchant portal visibility * reconciliation reports (via email or portal) These options are configured per merchant and can have any combination of the above. *** #### Email notifications[​](#email-notifications "Direct link to Email notifications") Email notifications are useful when the merchant wants a simple operational way to learn that a payment has been completed or needs attention. This is often suitable for lower-volume or less technical workflows where a team member reviews outcomes manually. *** #### Webhook or callback notifications[​](#webhook-or-callback-notifications "Direct link to Webhook or callback notifications") Webhook notifications are more suitable when the merchant wants payment outcomes delivered into their own systems. This can support processes such as: * updating a merchant-side payment status * reconciling payments against invoices or references * triggering internal business workflows More details can be found in our [Webhooks](/docs/resources/webhooks.md) guide. *** #### Reporting and reconciliation[​](#reporting-and-reconciliation "Direct link to Reporting and reconciliation") Reconciliation files are also available via email, or the Merchant Portal, which also contains payment history. *** #### Related pages[​](#related-pages "Direct link to Related pages") * [Overview](/docs/integration-options/payment-links.md) * [Setup & Branding](/docs/integration-options/payment-links/setup-and-branding.md) * [FAQ](/docs/integration-options/payment-links/faq.md) * [Webhooks](/docs/resources/webhooks.md) --- ### Setup & Branding This page explains the merchant logo setup and what the customer sees on a Payment Link. *** #### What this page covers[​](#what-this-page-covers "Direct link to What this page covers") This page explains: * what the merchant can brand on the page (logo only) * what the customer sees on the page * what merchants should confirm before the page is shared with customers *** #### Branding[​](#branding "Direct link to Branding") The only brandable element on a Payment Link is the **merchant logo**. The logo is displayed on the hosted checkout page so the customer can identify the merchant. All other page elements — layout, fields, wording, and payment methods — are part of the standard ZenPay-hosted experience and cannot be changed by the merchant. *** #### Customer fields[​](#customer-fields "Direct link to Customer fields") Payment Links include standard customer-facing fields such as: * customer name * customer email * contact number * payment amount * customer reference These fields are part of the standard page layout and are not editable or configurable by the merchant. *** #### Payment methods[​](#payment-methods "Direct link to Payment methods") Payment Links display the payment methods enabled for the merchant's account. The payment methods shown are determined by the merchant's account setup, not by page-level configuration. See [Payment Methods](/docs/resources/payment-methods.md) for the full list of methods supported on a Payment Link and how to change them. *** #### What merchants should confirm before go-live[​](#what-merchants-should-confirm-before-go-live "Direct link to What merchants should confirm before go-live") Before a Payment Link is shared with customers, merchants should confirm: * the correct merchant logo is displayed * the intended payment methods are enabled on their account * the merchant understands how payment outcomes will be communicated *** #### How this page should be used[​](#how-this-page-should-be-used "Direct link to How this page should be used") This page should support merchant onboarding and operational setup. It should not try to explain Hosted Checkout, plugin launch behaviour, or technical callback handling in detail. Those topics belong in other guides. *** #### Related pages[​](#related-pages "Direct link to Related pages") * [Overview](/docs/integration-options/payment-links.md) * [Notifications](/docs/integration-options/payment-links/notifications.md) * [FAQ](/docs/integration-options/payment-links/faq.md) --- ### URL Parameters Payment Links support prefilling customer and payment fields via URL query string so merchants can generate per-customer or per-invoice links without building a backend integration. #### Example[​](#example "Direct link to Example") `http://pay.sandbox.b2bpay.com.au/1337?customerName=Ian&paymentAmount=2.00&customerEmail=x@x.com` The merchant builds the URL (typically from a template in their CRM, invoicing system, or email platform) and shares it with the customer. When the customer opens the link, the hosted page loads with the values already filled in. #### Supported parameters[​](#supported-parameters "Direct link to Supported parameters") Query-string parameter names are case-insensitive, but **camelCase is the canonical form**. The parameters below map directly to fields on the Payment Link form — values passed in the URL are pre-filled when the page loads. ##### Always-available fields[​](#always-available-fields "Direct link to Always-available fields") | Parameter | Type | Required | Notes | | ------------------- | ------- | -------- | ---------------------------------------------- | | `customerName` | string | ✓ | Customer's full name | | `contactNumber` | string | ✓ | Numeric only, 6–15 digits | | `paymentAmount` | decimal | ✓ | In dollars (e.g. `2.00`). Minimum `1.00`. | | `customerReference` | string | ✓ | Merchant-supplied reference for reconciliation | ##### Program / merchant-configurable fields[​](#program--merchant-configurable-fields "Direct link to Program / merchant-configurable fields") Whether these fields appear on the Payment Link depends on the merchant account and program configuration. If the field is hidden in your program, the URL parameter is ignored. | Parameter | Type | Notes | | -------------------------- | ------ | ------------------------------------ | | `customerEmail` | string | Email format validation when present | | `companyName` | string | Max 250 chars | | `australianBusinessNumber` | string | ABN format | | `additionalReference` | string | Optional secondary reference | | `reference1` | string | Max 40 chars, hidden by default | | `reference2` | string | Max 40 chars, hidden by default | ##### SlicePay-only fields[​](#slicepay-only-fields "Direct link to SlicePay-only fields") Available when SlicePay is enabled on the merchant account (TravelPay merchants). | Parameter | Type | Notes | | --------------- | ---- | ---------------------------- | | `departureDate` | date | Only applicable for SlicePay | Card details (PAN, CVV, expiry), bank account details, and any sensitive credentials cannot be pre-filled via query string — customers always enter these directly on the hosted page. #### Locking fields with `state=disabled`[​](#locking-fields-with-statedisabled "Direct link to locking-fields-with-statedisabled") Appending `&state=disabled` to the URL greys out the form fields so the customer cannot edit the prefilled values. `http://pay.sandbox.b2bpay.com.au/1337?customerName=Ian&paymentAmount=2.00&state=disabled` Security: prefill values are hints, not server-signed Query-string parameters are **prefill hints only**. They are not cryptographically signed and not server-enforced. * A customer who edits the URL can change any prefilled value. * `state=disabled` is a **cosmetic UI lock** — it greys out the fields but does not enforce the values server-side. A user with basic browser dev tools (or who simply removes `state=disabled` from the URL) can edit the fields freely. * **Do not rely on URL parameters for trusted amount locking.** If a customer must not be able to change the amount (invoice collection, fixed-price products, etc.), use [Hosted Checkout](/docs/integration-options/hosted-checkout.md) with a server-generated fingerprint instead. The fingerprint is cryptographically tied to the amount and will reject any client-side tampering. #### When to use URL parameters[​](#when-to-use-url-parameters "Direct link to When to use URL parameters") Good fits: * Pre-filling customer details to reduce form friction * Per-invoice links where the amount is a convenience default (not trust-critical) * CRM/email-merge templates that generate payment URLs Poor fits: * Any scenario where the amount must be trusted — use Hosted Checkout instead * Per-customer tokenisation flows — use Hosted Checkout Mode 1 * Refund or backend operations — use the REST API #### Related[​](#related "Direct link to Related") * [Payment Links Overview](/docs/integration-options/payment-links.md) * [Setup & Branding](/docs/integration-options/payment-links/setup-and-branding.md) * [Hosted Checkout](/docs/integration-options/hosted-checkout.md) — for server-signed amount locking * [Hosted Checkout](/docs/integration-options/hosted-checkout.md) — fingerprint generation --- ### REST API The Zenith Payments Merchant API is the server-to-server integration surface for merchants who need backend control over payments, refunds, preauthorisations, customers, tokenised payment instruments, sessions, and related operations. Use this section for integration guidance. Use **/openapi** for the full endpoint, schema, and example reference. *** #### When to use the REST API[​](#when-to-use-the-rest-api "Direct link to When to use the REST API") Use the REST API when your integration is primarily backend-driven. Typical examples include: * creating and retrieving payments * creating refund requests and checking refund status * managing preauthorisations * creating or updating customers * working with tokenised payment instruments * creating secure sessions for Hosted Checkout * running reconciliation or operational checks If your main goal is to launch a hosted payment experience from your website or app, start with **Hosted Checkout** instead. If you want a hosted payment link with minimal integration effort, use **Payment Links**. *** #### What the API covers[​](#what-the-api-covers "Direct link to What the API covers") The Merchant API supports a broad set of merchant operations, including: * payments * preauths * refunds * customers (customer entities registered with Zenith Payments) * sessions * tokenisation and proxies * batch payments * request-to-pay flows * diagnostics This section does not try to repeat the full API reference. Its purpose is to explain how the API fits into a real integration and how to use it safely. *** #### How to use this section[​](#how-to-use-this-section "Direct link to How to use this section") Use the pages in this section for guidance: * **Authentication** — how Merchant API access works and how credentials should be handled * **Sessions and Hosted Checkout** — how backend-created sessions fit into plugin-based checkout * **Common API Patterns** — practical patterns for safe, maintainable integrations * **Refunds** — how refund request flows work at a practical level * **Payment Methods** — for conceptual detail on what each method is and when to use it, see [/docs/resources/payment-methods](/docs/resources/payment-methods.md). For field-level contracts on `/v2/cardproxies`, `/v2/proxies`, and `/v2/sessions`, see `/openapi`. * **API Reference** — full generated reference at `/openapi` *** #### API Reference[​](#api-reference "Direct link to API Reference") The complete endpoint and schema reference is available at: * [`/openapi`](/docs/integration-options/rest-api.md) Use `/openapi` when you need: * exact paths * request bodies * response schemas * examples * status codes * field-level detail Use the pages in this folder when you need: * guidance * integration patterns * trust boundaries * product-level context *** #### Relationship to Hosted Checkout[​](#relationship-to-hosted-checkout "Direct link to Relationship to Hosted Checkout") Hosted Checkout and the REST API are related, but they serve different roles. ##### Hosted Checkout[​](#hosted-checkout "Direct link to Hosted Checkout") Use Hosted Checkout when: * the browser launches checkout * Zenith hosts the payment UI * your frontend uses the JavaScript Plugin * your backend supports the flow with trusted session and validation logic * securely collecting payment details without touching sensitive data ##### REST API[​](#rest-api "Direct link to REST API") Use the REST API when: * your backend is the primary integration surface * you need direct operational control * you want to create, query, or manage merchant-side resources programmatically A typical integration may use both: * **REST API** for backend operations * **Hosted Checkout** for browser checkout launch *** #### Recommended reading order[​](#recommended-reading-order "Direct link to Recommended reading order") For most backend-led integrations, the best order is: 1. [Authentication](/docs/integration-options/rest-api/authentication.md) 2. [Sessions and Hosted Checkout](/docs/integration-options/rest-api/sessions-and-hosted-checkout.md) 3. [Common API Patterns](/docs/integration-options/rest-api/common-api-patterns.md) 4. [Refunds](/docs/integration-options/rest-api/refunds.md) 5. [API Reference](/docs/integration-options/rest-api.md) *** #### Summary[​](#summary "Direct link to Summary") The REST API is the backend integration surface for Zenith Payments. Use this section to understand how the API fits into your system, how to handle it safely, and how it works alongside Hosted Checkout. Use `/openapi` for the complete technical reference. --- ### API Integration Guide caution Whilst we do have an API to collect and tokenise card details, this requires PCI DSS certification. Please utilise our Payment Plugin to collect payment details for tokenisation. Contact us for more information if you do have PCI DSS certification. info This guide relies on information presented in the [Payment Plugin Guide](/docs/integration-options/hosted-checkout.md). #### Overview[​](#overview "Direct link to Overview") By utilising our payment plugin for secure tokenisation, and out /v2/payments and /v2/proxies API endpoints, you can safely take card, PayTo, and bank payments via API call. #### Tokenisation[​](#tokenisation "Direct link to Tokenisation") Please refer to our [Payment Plugin Guide](/docs/integration-options/hosted-checkout.md) for information on how to implement our payment plugin and details about tokenisation. * Load the payment plugin using `Mode: 1` * When payer enters their payment details, a payload (callback and/or webhook) will be returned with a token. * This token can then be either stored in a secure database against a customer or other identifiable entity, or used immediately. ##### Checking Token/Proxy status & pricing[​](#checking-tokenproxy-status--pricing "Direct link to Checking Token/Proxy status & pricing") * To check token status or get fee pricing (to display any fees that are passed on to the payer), you can use our /v2/proxies API. * You can also use the API to check PayTo mandate status. Please see the [PayTo Guide](/docs/resources/payment-methods/payto.md) for more details. **Example response** `GET /v2/proxies/\{token\}` ```json { "accountType": "Card", "cardHolderName": "Test Card", "cardNumber": "555555XXXXXX4444", "cardExpiry": "1230", "cardType": "MasterCard" } ``` * To get the fees for a token, and given amount, see the below examples **Example response** `GET /v2/proxies/\{token\}/pricing?paymentAmount=384.26` ```json { "pricing": { "customerFee": 38.43, "merchantFee": 0, "processingAmount": 422.69, "paymentAmount": 384.26 } } ``` #### Making Payments[​](#making-payments "Direct link to Making Payments") Once the token is obtained, you can charge the token using the `/v2/payments` API. caution Although in the API, `customerEmail`, `customerName`, and `merchantUniquePaymentId` are listed as optional - this is a legacy trait and all of these parameters should be treated as required to ensure there are no payment issues in the future. info Whilst both will work for card tokens, we strongly recommend using paymentAccountProxy instead of cardProxy to pass tokens via API to cover bank and PayTo tokens as well. * Pass the payment token using paymentAccountProxy, along with customer details and payment amount as a `POST` to `/v2/payments` **Example response** `POST /v2/payments` ```json { "paymentReference": "101994", "customerName": "Bolvar Fordragon", "customerReference": "CR-MKV4IG3D-JJM", "paymentStatus": "Successful", "baseAmount": 53.24, "fundsToMerchant": 53.24, "customerFee": 5.32, "merchantFee": 0, "paymentAmount": 58.56, "accountOrCardNo": "555555XXXXXX4444", "paymentAccount": "Card", "processingDate": "2026-01-26T23:08:10.6705202", "settlementDate": "2026-01-28T00:00:00", "processorReference": "fdf7281d280072bc4aa3", "isPaymentSettledToMerchant": false, "paymentCard": "MasterCard", "additionalReference": "API Example Test", "merchantName": "Menethil", "merchantCode": "1337", "merchantUniquePaymentId": "PAY-1769429288200", "isPaymentRetryScheduled": false, "isPaymentRecalled": false, "isPaymentRefunded": false, "transactionType": 1, "transactionTypeDisplay": "Charge", "isPaymentChargeBacked": false, "paymentSourceDisplay": "Api Tokenised Payment", "customerCode": "TR16553015" } ``` * For more information on the paymentStatus codes please see our [Status Codes](/docs/resources/payment-and-transaction-codes.md) * For more information on collecting payment information from API OR plugin payments, please see our [Reconciliation Guide](/docs/integration-guides/reconciliation.md). * For more information on charging a CML linked Customer entity (an entity that has a customer account with Zenith payments), please see our [Zenith Customer Entity Guide](/docs/integration-options/rest-api/cml-guide.md) ) --- ### Authentication The Merchant API is backend-only. Call it only from trusted server-side systems, and never expose your credentials in browser code, frontend bundles, or client-side storage. *** #### Authentication model[​](#authentication-model "Direct link to Authentication model") Merchant API requests use an API key plus Basic Authentication, both handled on the backend. The Authorization header holds the word `Basic`, a space, then a base64-encoded `username:password` string. *** #### Keep credentials on the backend[​](#keep-credentials-on-the-backend "Direct link to Keep credentials on the backend") Use Merchant API credentials for server-to-server work: creating and retrieving payments, refunds and preauthorisations, customer management, Hosted Checkout sessions, token and proxy operations, and diagnostics. Never expose them in browser JavaScript, frontend env files, mobile app bundles, client-side storage, screenshots, or logs a user could see. The safe pattern: 1. The frontend calls your backend. 2. Your backend authenticates to the Merchant API. 3. Your backend returns only the minimum data the frontend needs. This applies to Hosted Checkout too. Even though the frontend launches the modal, your backend still generates the session, holds the credentials, and validates the result. The browser only ever sees launch-safe values. *** #### Environment separation[​](#environment-separation "Direct link to Environment separation") Don't mix test, UAT, and production credentials. Configure base URLs, API keys, usernames/passwords, merchant codes, and callback URLs per environment, and store all of it in environment variables or a secret manager rather than in source control. *** #### Operational hygiene[​](#operational-hygiene "Direct link to Operational hygiene") * Limit who can access production credentials. * Rotate credentials through a controlled process. * Redact sensitive values in logs and support tooling. *** #### Related pages[​](#related-pages "Direct link to Related pages") * [REST API](/docs/integration-options/rest-api.md) * [Sessions and Hosted Checkout](/docs/integration-options/rest-api/sessions-and-hosted-checkout.md) * [Common API Patterns](/docs/integration-options/rest-api/common-api-patterns.md) * [API Reference](/docs/integration-options/rest-api.md) * [Security](/docs/security.md) *** #### Summary[​](#summary "Direct link to Summary") Authenticate with an API key and Basic Auth, keep credentials on the backend, and never mix environments. --- ### Zenith Customer Entity Guide Under Construction The hamsters powering this page called in sick today. CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION --- ### Common API Patterns The Merchant API is most effective when used as part of a clear backend integration model. This page outlines common patterns that help keep your implementation predictable, secure, and easier to maintain. *** #### 1. Keep the API on the backend[​](#1-keep-the-api-on-the-backend "Direct link to 1. Keep the API on the backend") The Merchant API is a privileged backend surface, your frontend should never call it directly. See [Authentication](/docs/integration-options/rest-api/authentication.md) for the full backend-only model and the safe request pattern. *** #### 2. Use unique merchant identifiers consistently[​](#2-use-unique-merchant-identifiers-consistently "Direct link to 2. Use unique merchant identifiers consistently") Where the API supports merchant-supplied unique identifiers (`merchantUniquePaymentID` aka MUPID), use them consistently. These identifiers make it easier to: * deduplicate retries * reconcile state safely * query the result of an earlier action * avoid duplicate creation bugs Do not treat them as optional bookkeeping. They are a practical part of robust API design. *** #### 3. Separate creation from retrieval[​](#3-separate-creation-from-retrieval "Direct link to 3. Separate creation from retrieval") For many integrations, it helps to think in two modes: * **write operations** — create or update something * **read operations** — confirm what happened A good pattern is: * create or request the action * store your local identifier mapping * retrieve or query later for confirmation or reconciliation This is especially useful for payments, refunds, preauth flows, and customer operations. *** #### 4. Treat the API as operational, not just transactional[​](#4-treat-the-api-as-operational-not-just-transactional "Direct link to 4. Treat the API as operational, not just transactional") The Merchant API is not only for "make a payment": it also covers customer management, token and proxy workflows, batch processing, request-to-pay, and diagnostics (see [Authentication](/docs/integration-options/rest-api/authentication.md) for the full list). That means it's often part of your backend operations layer, not just your checkout flow. *** #### 5. Use Sessions when the browser launches checkout[​](#5-use-sessions-when-the-browser-launches-checkout "Direct link to 5. Use Sessions when the browser launches checkout") If your frontend launches Hosted Checkout, do not move trust into browser code. See [Sessions and Hosted Checkout](/docs/integration-options/rest-api/sessions-and-hosted-checkout.md) for the full session flow. *** #### 6. Do not treat redirect as final truth[​](#6-do-not-treat-redirect-as-final-truth "Direct link to 6. Do not treat redirect as final truth") Redirect is useful for user experience, but it is not the source of payment truth, backend-confirmed state is (callbacks, webhooks, or API `GET` calls). See [Sessions and Hosted Checkout → Redirect and callback still matter](/docs/integration-options/rest-api/sessions-and-hosted-checkout.md#redirect-and-callback-still-matter) for details. This is one of the most important patterns in the whole documentation set. *** #### 7. Design for retries and idempotency[​](#7-design-for-retries-and-idempotency "Direct link to 7. Design for retries and idempotency") Networks fail, users retry, and backend actions can be repeated. Your integration should be designed so that repeated requests or repeated notifications do not cause duplicate side effects. Common ways to support this include: * stable merchant unique identifiers * backend state tracking * safe retry logic * explicit reconciliation queries *** #### 8. Keep environment configuration separate[​](#8-keep-environment-configuration-separate "Direct link to 8. Keep environment configuration separate") API integrations usually fail in messy ways when sandbox and production details are mixed. See [Authentication → Environment separation](/docs/integration-options/rest-api/authentication.md#environment-separation) for what to keep environment-specific. *** #### 9. Use `/openapi` for reference, not for design guidance[​](#9-use-openapi-for-reference-not-for-design-guidance "Direct link to 9-use-openapi-for-reference-not-for-design-guidance") The generated API reference is the source of truth for: * paths * schemas * examples * response codes Use these hand-written docs for: * architecture decisions * trust boundaries * safe integration patterns * choosing the right flow That split keeps your documentation cleaner and easier to maintain. *** #### 10. Build observability in from the start[​](#10-build-observability-in-from-the-start "Direct link to 10. Build observability in from the start") A production API integration should let you answer questions like: * what did we try to do? * what happened? * what state is the payment or customer in now? * can we safely retry? * can support reconcile this issue? That usually means robust logging, identifier mapping, and some form of operational query or audit trail in your backend. *** #### Related pages[​](#related-pages "Direct link to Related pages") * [REST API](/docs/integration-options/rest-api.md) * [Authentication](/docs/integration-options/rest-api/authentication.md) * [Sessions and Hosted Checkout](/docs/integration-options/rest-api/sessions-and-hosted-checkout.md) * [Hosted Checkout](/docs/integration-options/hosted-checkout.md) * [API Reference](/docs/integration-options/rest-api.md) *** #### Summary[​](#summary "Direct link to Summary") The Merchant API works best when it is treated as a trusted backend integration surface. Keep authentication and trust on the backend, use sessions for browser-launched checkout, design for retries and reconciliation, and rely on `/openapi` for exact reference detail. --- ### Errors Zenith Payments uses standard HTTP response codes to indicate whether a request succeeded or failed. This page covers the cross-cutting error semantics — response shape, each status code's meaning in context, and operational guidance for handling failures. For per-endpoint error responses with exact schemas and examples, see [`/openapi`](/docs/integration-options/rest-api.md). In general "status codes" in the 2XX range indicate success. Whereas, "status codes" in the 4XX range indicate a client-side error, which means that there was a failure in the information provided (e.g., a missing parameter, unauthorised access etc.). "Status codes" in the 5XX range indicate an error with Zenith Payment's internal servers. Please contact us if this occurs.. If the response code is not 2XX, it means the operation failed somehow and you may need to take action accordingly. You can check the response (which will be in JSON format) for a field called message which briefly explains the error reported. ```json { "message": "Invalid payment reference." } ``` *** #### Status codes returned by the API[​](#status-codes-returned-by-the-api "Direct link to Status codes returned by the API") The following codes are the complete set of HTTP statuses the Zenith Payments REST API can return. Any status code not listed here is **not** used by the API. | Status Code | **Error** | Explanation | | ----------- | ----------------- | ---------------------------------------------------------------------------------- | | 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. | | 401 | Unauthorized | No valid API key provided. | | 402 | Request Failure | The request has failed, however the variables were valid. | | 403 | Forbidden | The API key does not have the the right permissions to perform the request. | | 404 | Not Found | The requested resource doesn't exist. | | 409 | Too Many Requests | The API request limit is exceeded. Please see section Rate Limiting for more info. | | 5XX | Server Error | ZenPay servers have failed to process your request. | *** #### Handling `500` responses safely[​](#handling-500-responses-safely "Direct link to handling-500-responses-safely") A `500` response does **not** guarantee the operation failed. The resource may or may not have been created, updated, or submitted. Never assume failure on a `500` and retry blindly — that can cause duplicate payments, duplicate customers, or duplicate tokens. Safe handling pattern: 1. **Do not immediately retry** the same request. A second attempt with the same `merchantUniquePaymentId` or `customerUniqueId` may be rejected with a `409 Conflict` — or worse, it may succeed and create a duplicate. 2. **Query the resource** using the merchant-supplied identifier (`merchantUniquePaymentId`, `customerUniqueId`, or similar). If it exists, the original request succeeded — treat the `500` as transient. 3. **If the resource does not exist**, it is safe to submit a new request. 4. **Log the full response body and request ID** and escalate to Zenith Payments support if the pattern repeats. *** #### Debugging checklist[​](#debugging-checklist "Direct link to Debugging checklist") When investigating an error response: 1. Read the `message` field. 2. Note the HTTP status code and match it against the table above. 3. Capture the full request payload and response body. 4. Capture the request timestamp (UTC) and any merchant-side request identifier. 5. For `409` and `500` responses, check whether the resource already exists before retrying. 6. For `412` responses, check merchant configuration and the upstream provider. 7. For persistent `500` responses, escalate to Zenith Payments support with the captured context. *** #### Related[​](#related "Direct link to Related") * [`/openapi`](/docs/integration-options/rest-api.md) — per-endpoint response schemas and examples * [Common API Patterns](/docs/integration-options/rest-api/common-api-patterns.md) — idempotency, identifier reuse, retry design * [Authentication](/docs/integration-options/rest-api/authentication.md) — credential handling --- ### Create a batch payment [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Creates a batch payment from the supplied request payload. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 201 Created * 300 Multiple Choices * 400 Bad Request * 500 Internal Server Error Batch payment created successfully. Duplicate merchant unique id. The response will have 'Location' header which will have the orginal batch payment. **Response Headers** * **Location** Absolute URL of the original batch payment (its last path segment is the batchPaymentId). - application/json * Batch id resent after the first finished The same `merchantUniqueBatchId` resent after the first batch completed. No new batch: the `Location` header returns the original `batchPaymentId`. ```json { "message": "The merchant unique id already exists." } ``` Invalid batch payment details. Something went wrong. Batch payment may or may not be created. --- ### Get a batch payment [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the batch payment for the specified batch payment ID. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 404 Not Found * 500 Internal Server Error Batch Payment summary. Batch payment not found. Unable to get the batch payment. --- ### List batch payment entries [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the entries for the specified batch payment. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 404 Not Found * 500 Internal Server Error List of batch payment entries. Batch payment not found. Unable to get the batch payment. --- ### Create a card proxy [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Creates a card proxy from the supplied card details. Not recommended for software or sites that are not PCI DSS compliant. For an easy and secure card tokenisation and payment option, see the Payment Plugin. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 201 Created * 400 Bad Request * 403 Forbidden * 409 Conflict * 412 Precondition Failed Card authorisation is successful. Invalid input detail. The credential provided doesn't support this endpoint. * application/json - Tokenising not allowed This response has no body. Customer unique id is already used. Tokenisation failed. --- ### Delete a card proxy [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Deletes the specified card proxy without affecting customers already registered with it. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 204 No Content * 400 Bad Request * 404 Not Found Card proxy deleted successfully. * application/json - Card proxy deleted This response has no body. Invalid input detail. Unable to find the Card proxy provided. --- ### Get a card proxy [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the card proxy for the specified card proxy value. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found Token response of the card proxy provided. Invalid input detail. Unable to find the token response for the card proxy provided. --- ### Get card proxy pricing [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns pricing for the specified card proxy and payment amount. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found Pricing response for card proxy and payment amount provided. Invalid input detail. Unable to find the pricing response for the card proxy provided. --- ### Create a credit request [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Creates a credit request from the supplied request payload. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 201 Created * 400 Bad Request * 403 Forbidden * 409 Conflict * 412 Precondition Failed * 422 Unprocessable Entity * 500 Internal Server Error Credit created. Invalid input detail. Merchant is forbidden to perform this operation. UniqueId is not unique. Not allowed due to limit or not eligible to process. Merchant is forbidden to perform this operation. Something went wrong. Please try again. --- ### Get a credit request [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the credit request for the specified request unique ID. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 404 Not Found Found the credit. Unable to find the credit. --- ### Create a customer [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Creates a customer from the supplied request payload. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 201 Created * 300 Multiple Choices * 400 Bad Request * 403 Forbidden * 500 Internal Server Error Customer created successfully. Duplicate customer reference. Invalid input detail. Merchant is forbidden to perform this operation. Something went wrong. Customer may or may not be created. --- ### Get a customer [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the customer for the specified customer reference. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found Found the customer. Invalid customer reference. Unable to find the customer by the reference provided. --- ### Get a customer account [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the account details for the specified customer. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found Found the customer account. Invalid customer reference. Unable to find the customer by the reference provided. --- ### Get a customer payment option [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the payment option for the specified customer. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found Found the customer payment option. Invalid customer reference. Unable to find the customer by the reference provided. --- ### Get a customer profile [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the profile for the specified customer. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found Found the customer profile. Invalid customer reference. Unable to find the customer by the reference provided. --- ### Get customer status [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the status for the specified customer. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found Found the customer status. Invalid customer reference. Unable to find the customer by the reference provided. --- ### List customers [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns customers that match the supplied filter criteria. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found * 500 Internal Server Error Return all the customers satisfies the filters. Invalid get request. Unable to find the customers by the filters provided. Something went wrong. Please try again. --- ### Update a customer account [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Updates the account details for the specified customer. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 204 No Content * 400 Bad Request * 403 Forbidden * 500 Internal Server Error Updated the customer account. Invalid input detail. Merchant is forbidden to perform this operation. Something went wrong. Customer account may or may not be updated. --- ### Update a customer payment option [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Updates the payment option for the specified customer. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 204 No Content * 400 Bad Request * 403 Forbidden * 500 Internal Server Error Updated the customer payment option. Invalid input detail. Merchant is forbidden to perform this operation. Something went wrong. Customer payment option may or may not be updated. --- ### Update a customer profile [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Updates the profile for the specified customer. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 204 No Content * 400 Bad Request * 403 Forbidden * 500 Internal Server Error Updated the customer profile. Invalid input detail. Merchant is forbidden to perform this operation. Something went wrong. Customer may or may not be updated. --- ### Update a customer reference [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Updates the customer reference for the specified customer. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 204 No Content * 400 Bad Request * 403 Forbidden * 500 Internal Server Error Updated the customer reference. Invalid input detail. Merchant is forbidden to perform this operation. Something went wrong. Customer reference may or may not be updated. --- ### Update customer status [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Updates the status for the specified customer. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 204 No Content * 400 Bad Request * 403 Forbidden * 500 Internal Server Error Updated the customer status. Invalid input detail. Merchant is forbidden to perform this operation. Something went wrong. Customer payment option may or may not be updated. --- ### Ping the API [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the server date time and version information. #### Responses[​](#responses "Direct link to Responses") * 200 OK Ping response including server date time and version information. --- ### Merchant APIs [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Export * [OpenAPI Spec](/openapi-v2.json) ZenPay v2 REST Payment API. Supports: * Payments * Preauths * Refunds * CreditRequests * BatchPayments * Customers * CardProxies * Proxies * RequestPays * Sessions * Diagnostics #### Authentication[​](#authentication "Direct link to Authentication") * API Key: Api-Key * HTTP: Basic Auth Merchant's API key. Required together with Merchant's username and password | Security Scheme Type: | apiKey | | ---------------------- | ------- | | Header parameter name: | Api-Key | Merchant's username and password. Required together with the `Api-Key` header | Security Scheme Type: | http | | -------------------------- | ----- | | HTTP Authorization Scheme: | basic | ##### Contact ZenPay Integrations Team: URL: --- ### Create a payment [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Creates a payment from the supplied request payload. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 201 Created * 300 Multiple Choices * 400 Bad Request * 500 Internal Server Error Payment is processed. Duplicate merchant unique id. Invalid input detail. Something went wrong. Payment may or may not be created. --- ### Create a refund request [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Creates a refund request for the specified payment. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 201 Created * 300 Multiple Choices * 400 Bad Request * 403 Forbidden * 404 Not Found * 500 Internal Server Error Refund request is successfully created for the payment. Duplicate refund request. Invalid input detail. Merchant is forbidden to perform this operation. Payment not found. Something went wrong. Please try again. --- ### Get a payment [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the payment for the specified payment reference. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found Found the payment. Invalid payment reference. Unable to find the payment by the reference provided. --- ### Get a payment by merchant unique ID [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the payment for the specified merchant unique ID. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found Found the payment. Invalid payment reference. Unable to find the payment by the reference provided. --- ### Get a refund request [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the refund request for the specified payment and refund request unique ID. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found * 500 Internal Server Error Return refund request for the provided payment reference. Invalid input detail. Unable to find the refund request by the reference provided. Something went wrong. Please try again. --- ### List payments [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns payments that match the supplied filter criteria. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 500 Internal Server Error Return all the payments satisfies the filters. Invalid get request. Something went wrong. Please try again. --- ### List refund requests [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the refund requests for the specified payment. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found * 500 Internal Server Error Return refund request for the provided payment reference. Invalid input detail. Payment not found. Something went wrong. Please try again. --- ### Create a preauthorization [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Creates a preauthorization from the supplied request payload. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 201 Created * 300 Multiple Choices * 400 Bad Request * 403 Forbidden * 500 Internal Server Error Preauth is created. Duplicate merchant unique id. Invalid input detail. Invalid permission. Something went wrong. Preauth may or may not be created. --- ### Capture a preauthorization [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Captures the specified preauthorization. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 201 Created * 300 Multiple Choices * 400 Bad Request * 403 Forbidden * 404 Not Found * 500 Internal Server Error Preauth has been captured. The merchant unique id already exists. Invalid preauth reference. Invalid permission. Unable to find the preauth by the preauth reference provided. Something went wrong. Preauth may or may not be captured. --- ### Get a preauthorization by reference [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns preauthorization details for the specified preauthorization reference. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 404 Not Found Found the preauth. Unable to find the preauth by the reference provided. --- ### List preauthorizations [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns preauthorizations that match the supplied filter criteria. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK Found preauths. --- ### Void a preauthorization [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Voids the specified preauthorization. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 403 Forbidden * 404 Not Found * 500 Internal Server Error Preauth has been voided. Invalid preauth reference. Invalid permission. Unable to find the preauth by the preauth reference provided. Something went wrong. Preauth may or may not be voided. --- ### Get a proxy [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the payment account proxy for the specified proxy value. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found Payment account proxy provided. Invalid input detail. Unable to find the payment account proxy. --- ### Get proxy pricing [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns pricing for the specified proxy and payment amount. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 400 Bad Request * 404 Not Found Pricing response for proxy and payment amount provided. Invalid input detail. Unable to find the pricing response for the provided proxy. --- ### Create a request pay [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Creates a request pay from the supplied request payload. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 201 Created * 300 Multiple Choices * 400 Bad Request * 500 Internal Server Error Request to pay created successfully. Duplicate merchant unique id. * application/json - Request-pay batch id already used Duplicate submission response. ```json { "message": "The merchant unique id already exists." } ``` Invalid request pay details. Something went wrong. Request to pay may or may not be created. --- ### Get a request pay [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the request pay for the specified request pay ID. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 404 Not Found * 500 Internal Server Error Request Pay summary. Request to pay not found. Unable to get the request payment. --- ### List request pay entries [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the entries for the specified request pay. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 404 Not Found * 500 Internal Server Error List of request pay entries. Request pay not found. Unable to get the request to pay. --- ### 3D Secure Browser Data Cardholder browser data collected for 3D Secure authentication. **acceptHeader**string Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser. **colorDepth**integer\ Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. Possible values: 1, 4, 8, 15, 16, 24, 32, 48. **ipAddress**string IP address of the browser as returned by the HTTP headers to the 3DS Requestor. **language**string Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters. Value is returned from navigator.language property. **screenHeight**integer\ Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property. **screenWidth**integer\ Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property. **timezone**string Time difference between UTC time and the Cardholder browser local time, in minutes. The field is limited to 1-5 characters where the value is returned from the getTimezoneOffset() method. **userAgent**string Exact content of the HTTP user-agent header. The field is limited to maximum 2048 characters. Obtained from Cardholder browser using the navigator.userAgent property. 3D Secure Browser Data ```json { "acceptHeader": "string", "colorDepth": 0, "ipAddress": "string", "language": "string", "screenHeight": 0, "screenWidth": 0, "timezone": "string", "userAgent": "string" } ``` --- ### 3D Secure Data 3D Secure authentication configuration including browser data, callback URL, and redirect URL. **browserData** object Cardholder's browser data. Mandatory if UseThreeDSecure is true. **acceptHeader**string Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser. **colorDepth**integer\ Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. Possible values: 1, 4, 8, 15, 16, 24, 32, 48. **ipAddress**string IP address of the browser as returned by the HTTP headers to the 3DS Requestor. **language**string Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters. Value is returned from navigator.language property. **screenHeight**integer\ Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property. **screenWidth**integer\ Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property. **timezone**string Time difference between UTC time and the Cardholder browser local time, in minutes. The field is limited to 1-5 characters where the value is returned from the getTimezoneOffset() method. **userAgent**string Exact content of the HTTP user-agent header. The field is limited to maximum 2048 characters. Obtained from Cardholder browser using the navigator.userAgent property. **callbackUrl**string Endpoint to receive status notifications once 3DSecure is completed. Use \[uniqueId] (case sensitive) in URL to differentiate different payments and 3DS statuses For example: CallbackUrl [https://www.yourdomain.com.au/3dsecure/\[uniqueId](https://www.yourdomain.com.au/3dsecure/%5BuniqueId)] will be translated to assuming uniqueId is 123456. **redirectUrl**string Redirect URL used to redirect once the 3DSecure process is completed. Use \[uniqueId], \[status] (case sensitive) in URL to differentiate different payments and 3DS statuses For example: RedirectUrl [https://www.yourdomain.com.au/3dsecure/\[uniqueId\]?status=\[status](https://www.yourdomain.com.au/3dsecure/%5BuniqueId%5D?status=%5Bstatus)] will be translated to assuming uniqueId is 123456 Possible 3DSecure statuses: Success, Failed, Cancelled. **useThreeDSecure**boolean Will trigger 3DSecure process if enabled or valid for the card. 3D Secure Data ```json { "browserData": { "acceptHeader": "string", "colorDepth": 0, "ipAddress": "string", "language": "string", "screenHeight": 0, "screenWidth": 0, "timezone": "string", "userAgent": "string" }, "callbackUrl": "string", "redirectUrl": "string", "useThreeDSecure": true } ``` --- ### Additional Reference Additional customer reference entry containing a full name and customer reference. **customerReference**string Customer reference linked to this additional reference. **fullName**string Full name associated with the additional reference. Additional Reference ```json { "customerReference": "string", "fullName": "string" } ``` --- ### Ambiguous Result Response returned when a duplicate is detected (HTTP 300). Indicates the resource already exists. *** Ambiguous Result ```json {} ``` --- ### Bank Account Details Bank account details including BSB, account number, and account name. **accountName**stringrequired Account Holder name. **Constraints:** `<= 32 characters`, Value must match regular expression `[\u0020-\u007E]*` **accountNumber**stringrequired Bank Account number. **Format:** Value must match regular expression `^([0-9]{4,10})` **bankBranch**string Bank branch. **Max length:** `<= 50 characters` **bankName**string Bank Name. **Max length:** `<= 50 characters` **bsb**stringrequired BSB Number. Format: 000000. **Max length:** `<= 6 characters` **isPayTo**boolean Bank account is PayTo if true. **label**string Label for the account. **Max length:** `<= 50 characters` **payToStatus**integer\ If PayTo account, this field will let you know the status of the Mandate. **Possible values:** \[`0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`] Bank Account Details ```json { "accountName": "string", "accountNumber": "string", "bankBranch": "string", "bankName": "string", "bsb": "string", "isPayTo": true, "label": "string", "payToStatus": 0 } ``` --- ### Batch Payment Entry Individual entry within a batch payment including amount, status, and reference. **additionalReference**string Additional reference. (Conditional). **baseAmount**number\ Base amount of the payment is done. **cardCategory**string Card category. **cardTypeString**string Card scheme the payment was processed on, as text. For example: Visa. **cardTypeValue**integer\ Card scheme the payment was processed on, as its numeric code. Pairs with `cardTypeString`. **companyName**string Customer company name. **customerFee**number\ Fee charged on customer card. **customerName**string Customer who paid the payment. **customerReference**string Reference of the Customer who paid the payment. **entryStatus**string One of: * `BatchPay Entry Pending` — This Entry is waiting to be processed * `BatchPay Entry Processed` — Payment for this Entry has been successfully processed * `Customer not found` — This Customer is not found in system. Create the Customer using POST - /v2/customers API * `Duplicate entry` — There is a duplicate entry in the batch. Remove duplicate entry * `Multiple customers found` — The System has detected that there is Multiple Customers that have the same Reference setup. Check Customers and update reference * `Customer status is not open` — Corresponding customer for batchpay entry is not in open state. Update Customer Status to Open * `Payment end date has expired` — Payment End Date for BatchPay Entry has expired. Update Date to a future date * `Payment option is not BatchPay` — Customer's Payment Option needs to be BatchPay in order to be processed. Update Customer Payment Option to BatchPay * `Customer status does not allow payment processing` — Customer Status is invalid. Customer Status must be Open to process payments. Check Status of Customer * `Invalid payment amount` — Payment amount is not valid. Check amount and resubmit * `Error during payment processing` — There was an error while processing payment. Please contact Zenith Payments * `Technical Error` — This Entry has encountered an unhandled error. Please contact Zenith Payments * `Cancelled` — Batch is cancelled * `DuplicatePaymentUniqueId` — Duplicate payment unique id **failureCode**string Failure code if the payment failed. Please refer: for more details. (Conditional). **failureReason**string Failure reason if the payment failed. (Conditional). **isPaymentRecalled**boolean Payment recalled. **isPaymentRefunded**boolean Payment refunded. **isPaymentRetryScheduled**boolean Whether a retry payment is pending. Based on Program/Merchant settings, a failed payment will be retried. **lastDigits**string Payment Card No. **merchantCode**string Merchant code. **merchantFee**number\ Fee charged on Merchant. **merchantName**string Merchant trading name. **merchantUniquePaymentId**string Unique payment id provided by the merchant. (Conditional). **merchantWithheldAmount**number\ Funds to Merchant. **paymentAmount**number\ Total payment amount including the fees. **paymentCard**string Payment card used. **paymentDate**string\ Payment date. **paymentMethod**string Method was used to process the transaction. ie: Bank Account, Credit Card, etc. **paymentReference**string Unique Payment Reference for the payment done. **paymentResource**string Link to the actual payment. **paymentStatus**string One of: * `Pending` — This Payment is waiting to be processed * `Error` — This Payment has encountered an Error * `Submitted` — This Payment was successfully submitted * `Successful` — This Payment was successful * `Successful (Recalled)` — This Payment was Recalled. The System has detected that this Entry potentially has been submitted in another Batch * `Successful (Refunded)` — This Payment was Refunded * `Successful (Refunded) (Recalled)` — This Payment was Refunded and Recalled * `Failed` — This Payment has Failed * `Cancelled` — This Payment was Cancelled * `Suppressed` — This Payment was Suppressed * `InProgress` — This Payment is being processed **processedAmount**number\ Total payment amount including the fees. **processingDate**string\ Processing Date for the payment. Date Format: yyyy-MM-ddTHH:mm:ssZ, TimeZone: AEST. **processorReference**string Processor reference for the payment done. **recalledOn**string\ Recalled date. Date Format: yyyy-MM-ddTHH:mm:ssZ, TimeZone: AEST (Conditional). **recalledReason**string Reason. (Conditional). **refundedOn**string\ Refunded date. Date Format: yyyy-MM-ddTHH:mm:ssZ, TimeZone: AEST (Conditional). **refundedReason**string Reason. (Conditional). **retryPaymentReference**string Retry payment reference. (Conditional). **retryPaymentResource**string Link to the retry payment. **retryPaymentStatus**string Retry payment status. **retryScheduledOn**string\ Retry payment scheduled date. Date Format: yyyy-MM-ddTHH:mm:ssZ, TimeZone: AEST (Conditional). **settlementDate**string\ Settlement Date for the payment. This is a calculated date and may change until the payment been settled. Date Format: yyyy-MM-ddTHH:mm:ssZ, TimeZone: AEST. **settlementReference**string Reference for the settlement this entry was paid out in. Empty until the payment settles. **subCardTypeString**string Card sub-type where the scheme has one, as text. Empty when the scheme has none. **subCardTypeValue**integer\ Card sub-type as its numeric code. Pairs with `subCardTypeString`. Batch Payment Entry ```json { "additionalReference": "string", "baseAmount": 0, "cardCategory": "string", "cardTypeString": "string", "cardTypeValue": 0, "companyName": "string", "customerFee": 0, "customerName": "string", "customerReference": "string", "entryStatus": "string", "failureCode": "string", "failureReason": "string", "isPaymentRecalled": true, "isPaymentRefunded": true, "isPaymentRetryScheduled": true, "lastDigits": "string", "merchantCode": "string", "merchantFee": 0, "merchantName": "string", "merchantUniquePaymentId": "string", "merchantWithheldAmount": 0, "paymentAmount": 0, "paymentCard": "string", "paymentDate": "2024-07-29T15:51:28.071Z", "paymentMethod": "string", "paymentReference": "string", "paymentResource": "string", "paymentStatus": "string", "processedAmount": 0, "processingDate": "2024-07-29T15:51:28.071Z", "processorReference": "string", "recalledOn": "2024-07-29T15:51:28.071Z", "recalledReason": "string", "refundedOn": "2024-07-29T15:51:28.071Z", "refundedReason": "string", "retryPaymentReference": "string", "retryPaymentResource": "string", "retryPaymentStatus": "string", "retryScheduledOn": "2024-07-29T15:51:28.071Z", "settlementDate": "2024-07-29T15:51:28.071Z", "settlementReference": "string", "subCardTypeString": "string", "subCardTypeValue": 0 } ``` --- ### Batch Payment Entry Record Individual batch payment entry submitted by the client. Supports JSON or XML format. **customerReference**stringrequired Customer reference in individual payment batch entry. **merchantUniquePaymentId**string Unique payment id provided by the merchant. Can be used when Proxy payment is performed. (Optional). **Max length:** `<= 50 characters` **paymentAccountProxy**string Pass an alternative Proxy if required (Optional). If no Proxy is passed, the nominated card / bank account is used. **Max length:** `<= 40 characters` **paymentAmount**number\required Payment amount in individual payment batch entry. **Range:** `>= 0.01` and `<= 1.7976931348623157e+308` Batch Payment Entry Record ```json { "customerReference": "string", "merchantUniquePaymentId": "string", "paymentAccountProxy": "string", "paymentAmount": 0 } ``` --- ### Batch Payment Request Container for batch payment entries. Root element containing a collection of BatchPaymentEntry. **batchPaymentEntries** object\[]required Collection of BatchPayment entry. * Array \[ **customerReference**stringrequired Customer reference in individual payment batch entry. **merchantUniquePaymentId**string Unique payment id provided by the merchant. Can be used when Proxy payment is performed. (Optional). **Max length:** `<= 50 characters` **paymentAccountProxy**string Pass an alternative Proxy if required (Optional). If no Proxy is passed, the nominated card / bank account is used. **Max length:** `<= 40 characters` **paymentAmount**number\required Payment amount in individual payment batch entry. **Range:** `>= 0.01` and `<= 1.7976931348623157e+308` * ] **merchantUniqueBatchId**string Unique batch id provided by the merchant. **Max length:** `<= 50 characters` Batch Payment Request ```json { "batchPaymentEntries": [ { "customerReference": "string", "merchantUniquePaymentId": "string", "paymentAccountProxy": "string", "paymentAmount": 0 } ], "merchantUniqueBatchId": "string" } ``` --- ### Batch Payment Response Batch payment response returned after submission. **batchPaymentId**integer\ Id of BatchPayment. **merchantCode**string Merchant code. **merchantName**string Merchant trading name. **merchantUniqueBatchId**string Unique batch id provided by the merchant. **warningMessages**string WarningMessages after processing batch. Batch Payment Response ```json { "batchPaymentId": 0, "merchantCode": "string", "merchantName": "string", "merchantUniqueBatchId": "string", "warningMessages": "string" } ``` --- ### Batch Payment Summary Batch payment summary including status, totals, and processing details. **merchantCode**string Merchant code. **merchantName**string Merchant name (Trading name). **merchantUniqueBatchId**string Unique batch id provided by the merchant. **processingDate**string\ Batch processed date. **status**string One of: * `File Uploaded` — Batch file is uploaded and pending file processing * `Pending` — Payment is not processed yet * `Validation in Progress` — Batch validation is in progress * `On Hold - Potential Duplicate` — Batch is on hold awaiting manual activation * `Ready for Payment Processing` — Batch duplicate validation is completed and now it is ready for Payment processing * `On Hold Approved` * `Payment Processing in Progress` — Batch payment processing in progress * `Completed` — Batch payment processing completed * `Cancelled` — Batch payment is cancelled * `BatchPay Not Allowed` — Error in processing - Merchant status doesn't allow to process batch payment * `Merchant Not Found` — Error in file/batch processing merchant code in file not found in database * `Technical Error` — Any technical error like batch entry has been added twice **statusRemarks**string Status remarks. **submittedDate**string\ Batch submitted date. **totalAmount**number\ Total batch payment amount. **totalEntries**integer\ Total batch items in the batch. Batch Payment Summary ```json { "merchantCode": "string", "merchantName": "string", "merchantUniqueBatchId": "string", "processingDate": "2024-07-29T15:51:28.071Z", "status": "string", "statusRemarks": "string", "submittedDate": "2024-07-29T15:51:28.071Z", "totalAmount": 0, "totalEntries": 0 } ``` --- ### BPAY Detail BPAY details including biller code and biller reference. **billerCode**string BPAY Biller Code. **billerReference**string BPAY Biller Reference. BPAY Detail ```json { "billerCode": "string", "billerReference": "string" } ``` --- ### Card Proxy Token Response Card proxy token response including card proxy value, obfuscated card number, expiry, card type, and status. **cardNumber**string Obfuscated card number. **cardProxy**string Card proxy that can be used to process payment. **cardType**string Card type (Visa, MasterCard etc.). **expiry**string Card expiry in MM/yy format. **status**string Proxy status. Card Proxy Token Response ```json { "cardNumber": "string", "cardProxy": "string", "cardType": "string", "expiry": "string", "status": "string" } ``` --- ### Card Tokenization Request Credit or debit card details for card proxy creation. **cardHolderName**string Card holder name. **cardNumber**stringrequired Credit/Debit Card number. **customerUniqueId**string Customer unique identifier. **expiry**stringrequired Card expiry in MM/yy format. **Example: **`MM/yy` **paymentAmount**number\ Amount is optional. If provided, the applicable pricing will be returned in the result. **threeDSecureData** object Conditional. Pass the values if 3DSecure is required. **browserData** object Cardholder's browser data. Mandatory if UseThreeDSecure is true. **acceptHeader**string Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser. **colorDepth**integer\ Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. Possible values: 1, 4, 8, 15, 16, 24, 32, 48. **ipAddress**string IP address of the browser as returned by the HTTP headers to the 3DS Requestor. **language**string Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters. Value is returned from navigator.language property. **screenHeight**integer\ Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property. **screenWidth**integer\ Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property. **timezone**string Time difference between UTC time and the Cardholder browser local time, in minutes. The field is limited to 1-5 characters where the value is returned from the getTimezoneOffset() method. **userAgent**string Exact content of the HTTP user-agent header. The field is limited to maximum 2048 characters. Obtained from Cardholder browser using the navigator.userAgent property. **callbackUrl**string Endpoint to receive status notifications once 3DSecure is completed. Use \[uniqueId] (case sensitive) in URL to differentiate different payments and 3DS statuses For example: CallbackUrl [https://www.yourdomain.com.au/3dsecure/\[uniqueId](https://www.yourdomain.com.au/3dsecure/%5BuniqueId)] will be translated to assuming uniqueId is 123456. **redirectUrl**string Redirect URL used to redirect once the 3DSecure process is completed. Use \[uniqueId], \[status] (case sensitive) in URL to differentiate different payments and 3DS statuses For example: RedirectUrl [https://www.yourdomain.com.au/3dsecure/\[uniqueId\]?status=\[status](https://www.yourdomain.com.au/3dsecure/%5BuniqueId%5D?status=%5Bstatus)] will be translated to assuming uniqueId is 123456 Possible 3DSecure statuses: Success, Failed, Cancelled. **useThreeDSecure**boolean Will trigger 3DSecure process if enabled or valid for the card. Card Tokenization Request ```json { "cardHolderName": "string", "cardNumber": "string", "customerUniqueId": "string", "expiry": "MM/yy", "paymentAmount": 0, "threeDSecureData": { "browserData": { "acceptHeader": "string", "colorDepth": 0, "ipAddress": "string", "language": "string", "screenHeight": 0, "screenWidth": 0, "timezone": "string", "userAgent": "string" }, "callbackUrl": "string", "redirectUrl": "string", "useThreeDSecure": true } } ``` --- ### Card Tokenization Response Card authorisation response returned after card proxy creation. **cardNumber**string Obfuscated card number. **cardProxy**string Processor token. Used to make payment next time. **cardType**string Card type (Visa, MasterCard etc.). **expiry**string Card expiry in MM/yy format. **failureCode**string Failure code in case the authorisation fails. **failureReason**string Failure reason in case the authorisation fails. **pricing** object Applicable pricing based on provided card and payment details. **customerFee**number\ Fee paid by the customer. **merchantFee**number\ Fee paid by the merchant. **paymentAmount**number\ Payment amount i.e. base amount excluding any fee. **processingAmount**number\ Total amount charged to the card, including any fee. **redirectUrl**string 3DSecure redirect url to complete the 3DSecure challege if required by the scheme. **status**string Proxy status Expected Statuses 1. Pending This proxy is waiting be to processed 2. Successful - This proxy was successful 3. Failed - This proxy has Failed 4. PendingThreeDS - This proxy needs to complete 3DSecure process using the RedirectUrl. Card Tokenization Response ```json { "cardNumber": "string", "cardProxy": "string", "cardType": "string", "expiry": "string", "failureCode": "string", "failureReason": "string", "pricing": { "customerFee": 0, "merchantFee": 0, "paymentAmount": 0, "processingAmount": 0 }, "redirectUrl": "string", "status": "string" } ``` --- ### Credit Card Credit card details including card number, type, expiry, and label. **cardNumber**string Card number. **cardType**string Card Type. **expiry**string Expiry. **label**string Label for the card. Credit Card ```json { "cardNumber": "string", "cardType": "string", "expiry": "string", "label": "string" } ``` --- ### Credit Card Proxy Credit card proxy reference with optional label. **cardProxy**stringrequired Card proxy generated by the /cardproxies api. **Max length:** `<= 40 characters` **label**string Label for the card. **Max length:** `<= 80 characters` Credit Card Proxy ```json { "cardProxy": "string", "label": "string" } ``` --- ### Credit Disbursement Request Credit request details including customer reference, amount, payment account proxy, and reason. **creditAmount**number\required Payment amount. **customerName**stringrequired Customer name. **Max length:** `<= 100 characters` **customerReference**stringrequired Customer reference. **Max length:** `<= 20 characters` **paymentAccountProxy**stringrequired Payment Account Proxy. **Max length:** `<= 50 characters` **reason**stringrequired Credit reason. **Max length:** `<= 50 characters` **requestUniqueId**stringrequired Unique credit id provided by the merchant. **Max length:** `<= 50 characters` Credit Disbursement Request ```json { "creditAmount": 0, "customerName": "string", "customerReference": "string", "paymentAccountProxy": "string", "reason": "string", "requestUniqueId": "string" } ``` --- ### Credit Request Response Credit request details including status, credit reference, amount, and merchant information. **cancelReason**string Reason the credit request was cancelled. **creditAmount**number\ Credit request amount. **creditReference**integer\ Reference for the credit transaction. **merchantCode**string Merchant code. **merchantName**string Merchant trading name. **rejectReason**string Reason the credit request was rejected. **requestReason**string Reason for the credit request. **requestStatus**integer\ Status code of the credit request. **requestStatusString**string Status label for the credit request. **requestUniqueId**string Unique identifier for the credit request. **status**integer\ Status code of the credit request. | Enum Value | Description | | ---------- | -------------------- | | 0 | Forbidden | | 1 | CountLimitReached | | 2 | AmountLimitReached | | 3 | InvalidPaymentProxy | | 4 | DuplicateRequest | | 5 | NotEligibleForCredit | | 6 | Success | Credit Request Response ```json { "cancelReason": "string", "creditAmount": 0, "creditReference": 0, "merchantCode": "string", "merchantName": "string", "rejectReason": "string", "requestReason": "string", "requestStatus": 0, "requestStatusString": "string", "requestUniqueId": "string", "status": 0 } ``` --- ### Customer Account Response Customer payment account including bank account and credit card details. **bankAccount** object Customer bank account details. **accountName**stringrequired Account Holder name. **Constraints:** `<= 32 characters`, Value must match regular expression `[\u0020-\u007E]*` **accountNumber**stringrequired Bank Account number. **Format:** Value must match regular expression `^([0-9]{4,10})` **bankBranch**string Bank branch. **Max length:** `<= 50 characters` **bankName**string Bank Name. **Max length:** `<= 50 characters` **bsb**stringrequired BSB Number. Format: 000000. **Max length:** `<= 6 characters` **isPayTo**boolean Bank account is PayTo if true. **label**string Label for the account. **Max length:** `<= 50 characters` **payToStatus**integer\ If PayTo account, this field will let you know the status of the Mandate. **Possible values:** \[`0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`] **creditCard** object Customer credit card details. **cardNumber**string Card number. **cardType**string Card Type. **expiry**string Expiry. **label**string Label for the card. Customer Account Response ```json { "bankAccount": { "accountName": "string", "accountNumber": "string", "bankBranch": "string", "bankName": "string", "bsb": "string", "isPayTo": true, "label": "string", "payToStatus": 0 }, "creditCard": { "cardNumber": "string", "cardType": "string", "expiry": "string", "label": "string" } } ``` --- ### Customer Address Customer address including address lines, suburb, state, postcode, and country. **address1**stringrequired Address line 1. **address2**string Address line 2. **country**stringrequired Country. **Max length:** `<= 100 characters` **postcode**stringrequired Postcode. **state**stringrequired State / province. **Max length:** `<= 50 characters` **suburb**stringrequired Suburb / city. **Max length:** `<= 50 characters` Customer Address ```json { "address1": "string", "address2": "string", "country": "string", "postcode": "string", "state": "string", "suburb": "string" } ``` --- ### Customer Creation Response Customer creation response including assigned references and payment option details. **abn**string Australian Business Number. **additionalPaymentAccountProxies** object\[] Additional PaymentAccountProxies. Proxy is generated using the Payments Plugin for Bank and Credit/Debit Card or /cardProxies api for Credit/Debit Card. * Array \[ **label**string Label for the account. **Max length:** `<= 80 characters` **proxy**stringrequired Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies api for card. **Max length:** `<= 40 characters` * ] **additionalReferences** object\[] Additional references if you have more than one references to manage. Eg: Parents paying childcare fee for more than one kid. * Array \[ **customerReference**string Customer reference linked to this additional reference. **fullName**string Full name associated with the additional reference. * ] **address** object Customer address. **address1**stringrequired Address line 1. **address2**string Address line 2. **country**stringrequired Country. **Max length:** `<= 100 characters` **postcode**stringrequired Postcode. **state**stringrequired State / province. **Max length:** `<= 50 characters` **suburb**stringrequired Suburb / city. **Max length:** `<= 50 characters` **bPayDetail** object BPAY details. **billerCode**string BPAY Biller Code. **billerReference**string BPAY Biller Reference. **bankAccount** object Customer bank account details. **accountName**stringrequired Account Holder name. **Constraints:** `<= 32 characters`, Value must match regular expression `[\u0020-\u007E]*` **accountNumber**stringrequired Bank Account number. **Format:** Value must match regular expression `^([0-9]{4,10})` **bankBranch**string Bank branch. **Max length:** `<= 50 characters` **bankName**string Bank Name. **Max length:** `<= 50 characters` **bsb**stringrequired BSB Number. Format: 000000. **Max length:** `<= 6 characters` **isPayTo**boolean Bank account is PayTo if true. **label**string Label for the account. **Max length:** `<= 50 characters` **payToStatus**integer\ If PayTo account, this field will let you know the status of the Mandate. **Possible values:** \[`0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`] **billerCode**string If BPAY payment method is enabled, biller code will be returned. **billerReference**string If BPAY payment method is enabled, biller reference can be used by the customer to make BPAY payment. **card** object Customer credit / debit card proxy. (Token is generated using the /tokens api. **cardProxy**stringrequired Card proxy generated by the /cardproxies api. **Max length:** `<= 40 characters` **label**string Label for the card. **Max length:** `<= 80 characters` **customerCompanyName**string Company name if this is company account. **customerLogin**string Customer login. **customerReference**stringrequired Customer / Parent Reference. Should be unique and provided by the merchant. If you are paying the merchant by BPAY, this should be your BPAY Reference. **dateOfBirth**string\required Date of birth. Customer must be atleast 16 years old. **email**stringrequired Email address. **enableBPayOption**boolean Allows to enable BPAY option for the customer / parent. **fax**string Fax number. **firstName**stringrequired First name. **Max length:** `<= 30 characters` **isBPayCrnPassed**boolean Send this as true when customer reference passed if CRN. Default is set to false if not passed. **lastName**stringrequired Last name. **Max length:** `<= 30 characters` **merchantCode**string Merchant code. **merchantName**string Merchant trading name. **merchantStaffMember**string Merchant Staff member assigned to this customer / parent. **mobile**stringrequired Mobile number. **notificationMethod**integer\required Notification method used to indicate the communication channel when payment successful or failed. | Enum Value | Description | | ---------- | ----------- | | 0 | None | | 1 | Sms | | 2 | Email | **passwordGenerationUrl**string Password generation for customer login. **payIdDetail** object PayID details. **payId**string PayID. **payIdName**string PayID Name. **reference**string Reference. **paymentAccountProxy** object This replaces the BankAccount and Card properties. Proxy is generated using the Payments Plugin for Bank and Credit/Debit Card or /cardProxies api for Credit/Debit Card. **label**string Label for the account. **Max length:** `<= 80 characters` **proxy**stringrequired Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies api for card. **Max length:** `<= 40 characters` **paymentAmount**number\required Payment amount. Set the default amount for auto payments or amount for one-off payment. **paymentEndDate**string\ Payment end date. **paymentFrequency**integer\required Payment frequency. Applicable to auto pay, email reminder and sms reminder. | Enum Value | Description | | ---------- | ----------- | | 32 | Weekly | | 33 | Fortnightly | | 34 | Quarterly | | 35 | HalfYearly | | 36 | Yearly | | 37 | FourWeeks | | 38 | Monthly | **paymentOption**integer\required Payment option. Use the correct payment option which is supported by the merchant. | Enum Value | Description | | ---------- | ------------- | | 22 | AutoPay | | 23 | EmailReminder | | 24 | SmsReminder | | 25 | FixedTerm | | 26 | BatchPay | | 27 | ScheduledPay | | 28 | OneOff | | 148 | PayID | | 149 | BPAY | **paymentStartDate**string\required Payment start date. **phone**string Phone number. **promotionCode**string Promotion code if any. **sendWelcomeEmail**boolean Sends welcome email if set to true. Default is set to true if not passed. **title**string Provide the salutation. Eg: Mr or Mrs. **Max length:** `<= 10 characters` **websiteUrl**string Website URL if any. Customer Creation Response ```json { "abn": "string", "additionalPaymentAccountProxies": [ { "label": "string", "proxy": "string" } ], "additionalReferences": [ { "customerReference": "string", "fullName": "string" } ], "address": { "address1": "string", "address2": "string", "country": "string", "postcode": "string", "state": "string", "suburb": "string" }, "bPayDetail": { "billerCode": "string", "billerReference": "string" }, "bankAccount": { "accountName": "string", "accountNumber": "string", "bankBranch": "string", "bankName": "string", "bsb": "string", "isPayTo": true, "label": "string", "payToStatus": 0 }, "billerCode": "string", "billerReference": "string", "card": { "cardProxy": "string", "label": "string" }, "customerCompanyName": "string", "customerLogin": "string", "customerReference": "string", "dateOfBirth": "2024-07-29T15:51:28.071Z", "email": "string", "enableBPayOption": true, "fax": "string", "firstName": "string", "isBPayCrnPassed": true, "lastName": "string", "merchantCode": "string", "merchantName": "string", "merchantStaffMember": "string", "mobile": "string", "notificationMethod": 0, "passwordGenerationUrl": "string", "payIdDetail": { "payId": "string", "payIdName": "string", "reference": "string" }, "paymentAccountProxy": { "label": "string", "proxy": "string" }, "paymentAmount": 0, "paymentEndDate": "2024-07-29T15:51:28.071Z", "paymentFrequency": 32, "paymentOption": 22, "paymentStartDate": "2024-07-29T15:51:28.071Z", "phone": "string", "promotionCode": "string", "sendWelcomeEmail": true, "title": "string", "websiteUrl": "string" } ``` --- ### Customer Details Response Customer details including profile, payment account, payment option, and merchant information. **account** object Customer Payment account. **bankAccount** object Customer bank account details. **accountName**stringrequired Account Holder name. **Constraints:** `<= 32 characters`, Value must match regular expression `[\u0020-\u007E]*` **accountNumber**stringrequired Bank Account number. **Format:** Value must match regular expression `^([0-9]{4,10})` **bankBranch**string Bank branch. **Max length:** `<= 50 characters` **bankName**string Bank Name. **Max length:** `<= 50 characters` **bsb**stringrequired BSB Number. Format: 000000. **Max length:** `<= 6 characters` **isPayTo**boolean Bank account is PayTo if true. **label**string Label for the account. **Max length:** `<= 50 characters` **payToStatus**integer\ If PayTo account, this field will let you know the status of the Mandate. **Possible values:** \[`0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`] **creditCard** object Customer credit card details. **cardNumber**string Card number. **cardType**string Card Type. **expiry**string Expiry. **label**string Label for the card. **merchantCode**string Merchant code. **merchantName**string Merchant trading name. **paymentOption** object Customer payment option. **bPayDetail** object BPAY details. **billerCode**string BPAY Biller Code. **billerReference**string BPAY Biller Reference. **nextPaymentDate**string\required Payment start date. **notificationMethod**integer\required Notification method used to indicate the communication channel when payment successful or failed. | Enum Value | Description | | ---------- | ----------- | | 0 | None | | 1 | Sms | | 2 | Email | **payIdDetail** object PayID details. **payId**string PayID. **payIdName**string PayID Name. **reference**string Reference. **paymentAmount**number\required Payment amount. Set the default amount for auto payments or amount for one-off payment. **paymentEndDate**string\ Payment end date. **paymentFrequency**integer\required Payment frequency. Applicable to auto pay, email reminder and sms reminder. Returns monthly if frequency is not available. | Enum Value | Description | | ---------- | ----------- | | 32 | Weekly | | 33 | Fortnightly | | 34 | Quarterly | | 35 | HalfYearly | | 36 | Yearly | | 37 | FourWeeks | | 38 | Monthly | **paymentOption**integer\required Payment option. Use the correct payment option which is supported by the merchant. | Enum Value | Description | | ---------- | ------------- | | 22 | AutoPay | | 23 | EmailReminder | | 24 | SmsReminder | | 25 | FixedTerm | | 26 | BatchPay | | 27 | ScheduledPay | | 28 | OneOff | | 148 | PayID | | 149 | BPAY | **profile** object Customer profile. **abn**string Australian Business Number. **address** object Customer postal address. **address1**stringrequired Address line 1. **address2**string Address line 2. **country**stringrequired Country. **Max length:** `<= 100 characters` **postcode**stringrequired Postcode. **state**stringrequired State / province. **Max length:** `<= 50 characters` **suburb**stringrequired Suburb / city. **Max length:** `<= 50 characters` **bPayReference**string BPay reference number for the customer. **companyName**string Name of the customer company. **customerCode**string Unique code assigned to the customer. **customerReference**string Unique reference identifier for the customer. **customerStatus**string Current status of the customer account. **dateClosed**string\ Date the customer account was closed. **dateOfBirth**string\ Customer date of birth. **email**string Customer email address. **enableBPayOption**boolean Whether BPay payment option is enabled for this customer. **fax**string Customer fax number. **firstName**string Customer first name. **lastName**string Customer last name. **merchantStaffMember**string Staff member assigned to the customer. **mobile**string Customer mobile phone number. **openDate**string\ Date the customer account was opened. **phone**string Customer phone number. **title**string Customer title (e.g. Mr, Mrs, Ms). Customer Details Response ```json { "account": { "bankAccount": { "accountName": "string", "accountNumber": "string", "bankBranch": "string", "bankName": "string", "bsb": "string", "isPayTo": true, "label": "string", "payToStatus": 0 }, "creditCard": { "cardNumber": "string", "cardType": "string", "expiry": "string", "label": "string" } }, "merchantCode": "string", "merchantName": "string", "paymentOption": { "bPayDetail": { "billerCode": "string", "billerReference": "string" }, "nextPaymentDate": "2024-07-29T15:51:28.071Z", "notificationMethod": 0, "payIdDetail": { "payId": "string", "payIdName": "string", "reference": "string" }, "paymentAmount": 0, "paymentEndDate": "2024-07-29T15:51:28.071Z", "paymentFrequency": 32, "paymentOption": 22 }, "profile": { "abn": "string", "address": { "address1": "string", "address2": "string", "country": "string", "postcode": "string", "state": "string", "suburb": "string" }, "bPayReference": "string", "companyName": "string", "customerCode": "string", "customerReference": "string", "customerStatus": "string", "dateClosed": "2024-07-29T15:51:28.071Z", "dateOfBirth": "2024-07-29T15:51:28.071Z", "email": "string", "enableBPayOption": true, "fax": "string", "firstName": "string", "lastName": "string", "merchantStaffMember": "string", "mobile": "string", "openDate": "2024-07-29T15:51:28.071Z", "phone": "string", "title": "string" } } ``` --- ### Customer Payment Account Update Customer payment account update. Accepts PaymentAccountProxy, CreditCardProxy, or BankAccount. Priority order: PaymentAccountProxy, BankAccount, CreditCardProxy. Preferred option is PaymentAccountProxy. **addtionalPaymentAccountProxies** object\[] Additional PaymentAccountProxies. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies API for card. * Array \[ **label**string Label for the account. **Max length:** `<= 80 characters` **proxy**stringrequired Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies api for card. **Max length:** `<= 40 characters` * ] **bankAccount** object Customer bank account details. Provide valid BSB and Account Number. **accountName**stringrequired Account Holder name. **Constraints:** `<= 32 characters`, Value must match regular expression `[\u0020-\u007E]*` **accountNumber**stringrequired Bank Account number. **Format:** Value must match regular expression `^([0-9]{4,10})` **bankBranch**string Bank branch. **Max length:** `<= 50 characters` **bankName**string Bank Name. **Max length:** `<= 50 characters` **bsb**stringrequired BSB Number. Format: 000000. **Max length:** `<= 6 characters` **isPayTo**boolean Bank account is PayTo if true. **label**string Label for the account. **Max length:** `<= 50 characters` **payToStatus**integer\ If PayTo account, this field will let you know the status of the Mandate. **Possible values:** \[`0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`] **creditCardProxy** object Customer credit / debit card proxy. Proxy is generated using the /cardProxies API or Payments Plugin. **cardProxy**stringrequired Card proxy generated by the /cardproxies api. **Max length:** `<= 40 characters` **label**string Label for the card. **Max length:** `<= 80 characters` **paymentAccountProxy** object This replaces the BankAccount and CreditCardProxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies API for card. **label**string Label for the account. **Max length:** `<= 80 characters` **proxy**stringrequired Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies api for card. **Max length:** `<= 40 characters` Customer Payment Account Update ```json { "addtionalPaymentAccountProxies": [ { "label": "string", "proxy": "string" } ], "bankAccount": { "accountName": "string", "accountNumber": "string", "bankBranch": "string", "bankName": "string", "bsb": "string", "isPayTo": true, "label": "string", "payToStatus": 0 }, "creditCardProxy": { "cardProxy": "string", "label": "string" }, "paymentAccountProxy": { "label": "string", "proxy": "string" } } ``` --- ### Customer Payment Option Customer payment option including payment type, amount, frequency, schedule, and notification method. **bPayDetail** object BPAY details. **billerCode**string BPAY Biller Code. **billerReference**string BPAY Biller Reference. **nextPaymentDate**string\required Payment start date. **notificationMethod**integer\required Notification method used to indicate the communication channel when payment successful or failed. | Enum Value | Description | | ---------- | ----------- | | 0 | None | | 1 | Sms | | 2 | Email | **payIdDetail** object PayID details. **payId**string PayID. **payIdName**string PayID Name. **reference**string Reference. **paymentAmount**number\required Payment amount. Set the default amount for auto payments or amount for one-off payment. **paymentEndDate**string\ Payment end date. **paymentFrequency**integer\required Payment frequency. Applicable to auto pay, email reminder and sms reminder. Returns monthly if frequency is not available. | Enum Value | Description | | ---------- | ----------- | | 32 | Weekly | | 33 | Fortnightly | | 34 | Quarterly | | 35 | HalfYearly | | 36 | Yearly | | 37 | FourWeeks | | 38 | Monthly | **paymentOption**integer\required Payment option. Use the correct payment option which is supported by the merchant. | Enum Value | Description | | ---------- | ------------- | | 22 | AutoPay | | 23 | EmailReminder | | 24 | SmsReminder | | 25 | FixedTerm | | 26 | BatchPay | | 27 | ScheduledPay | | 28 | OneOff | | 148 | PayID | | 149 | BPAY | Customer Payment Option ```json { "bPayDetail": { "billerCode": "string", "billerReference": "string" }, "nextPaymentDate": "2024-07-29T15:51:28.071Z", "notificationMethod": 0, "payIdDetail": { "payId": "string", "payIdName": "string", "reference": "string" }, "paymentAmount": 0, "paymentEndDate": "2024-07-29T15:51:28.071Z", "paymentFrequency": 32, "paymentOption": 22 } ``` --- ### Customer Profile Customer profile including personal details, contact information, address, and account dates. **abn**string Australian Business Number. **address** object Customer postal address. **address1**stringrequired Address line 1. **address2**string Address line 2. **country**stringrequired Country. **Max length:** `<= 100 characters` **postcode**stringrequired Postcode. **state**stringrequired State / province. **Max length:** `<= 50 characters` **suburb**stringrequired Suburb / city. **Max length:** `<= 50 characters` **bPayReference**string BPay reference number for the customer. **companyName**string Name of the customer company. **customerCode**string Unique code assigned to the customer. **customerReference**string Unique reference identifier for the customer. **customerStatus**string Current status of the customer account. **dateClosed**string\ Date the customer account was closed. **dateOfBirth**string\ Customer date of birth. **email**string Customer email address. **enableBPayOption**boolean Whether BPay payment option is enabled for this customer. **fax**string Customer fax number. **firstName**string Customer first name. **lastName**string Customer last name. **merchantStaffMember**string Staff member assigned to the customer. **mobile**string Customer mobile phone number. **openDate**string\ Date the customer account was opened. **phone**string Customer phone number. **title**string Customer title (e.g. Mr, Mrs, Ms). Customer Profile ```json { "abn": "string", "address": { "address1": "string", "address2": "string", "country": "string", "postcode": "string", "state": "string", "suburb": "string" }, "bPayReference": "string", "companyName": "string", "customerCode": "string", "customerReference": "string", "customerStatus": "string", "dateClosed": "2024-07-29T15:51:28.071Z", "dateOfBirth": "2024-07-29T15:51:28.071Z", "email": "string", "enableBPayOption": true, "fax": "string", "firstName": "string", "lastName": "string", "merchantStaffMember": "string", "mobile": "string", "openDate": "2024-07-29T15:51:28.071Z", "phone": "string", "title": "string" } ``` --- ### Customer Profile Details Customer profile details returned for a customer profile query. **abn**string Australian Business Number. **address** object Customer postal address. **address1**stringrequired Address line 1. **address2**string Address line 2. **country**stringrequired Country. **Max length:** `<= 100 characters` **postcode**stringrequired Postcode. **state**stringrequired State / province. **Max length:** `<= 50 characters` **suburb**stringrequired Suburb / city. **Max length:** `<= 50 characters` **companyName**string Name of the customer company. **dateOfBirth**string\ Customer date of birth. **email**string Customer email address. **enableBPayOption**boolean Whether BPay payment option is enabled for this customer. **fax**string Customer fax number. **firstName**string Customer first name. **lastName**string Customer last name. **merchantStaffMember**string Staff member assigned to the customer. **mobile**string Customer mobile phone number. **phone**string Customer phone number. **title**string Customer title (e.g. Mr, Mrs, Ms). Customer Profile Details ```json { "abn": "string", "address": { "address1": "string", "address2": "string", "country": "string", "postcode": "string", "state": "string", "suburb": "string" }, "companyName": "string", "dateOfBirth": "2024-07-29T15:51:28.071Z", "email": "string", "enableBPayOption": true, "fax": "string", "firstName": "string", "lastName": "string", "merchantStaffMember": "string", "mobile": "string", "phone": "string", "title": "string" } ``` --- ### Customer Profile Request Customer profile details for creating or updating a customer profile. **abn**string Australian Business Number. **address** objectrequired Customer postal address. **address1**stringrequired Address line 1. **address2**string Address line 2. **country**stringrequired Country. **Max length:** `<= 100 characters` **postcode**stringrequired Postcode. **state**stringrequired State / province. **Max length:** `<= 50 characters` **suburb**stringrequired Suburb / city. **Max length:** `<= 50 characters` **companyName**string Name of the customer company. **dateOfBirth**string\required Customer date of birth. **email**stringrequired Customer email address. **enableBPayOption**boolean Whether BPay payment option is enabled for this customer. **fax**string Customer fax number. **firstName**stringrequired First name. **Max length:** `<= 30 characters` **lastName**stringrequired Last name. **Max length:** `<= 30 characters` **merchantStaffMember**string Staff member assigned to the customer. **mobile**string Customer mobile phone number. **phone**string Customer phone number. **title**string Provide the salutation. Eg: Mr or Mrs. **Max length:** `<= 10 characters` Customer Profile Request ```json { "abn": "string", "address": { "address1": "string", "address2": "string", "country": "string", "postcode": "string", "state": "string", "suburb": "string" }, "companyName": "string", "dateOfBirth": "2024-07-29T15:51:28.071Z", "email": "string", "enableBPayOption": true, "fax": "string", "firstName": "string", "lastName": "string", "merchantStaffMember": "string", "mobile": "string", "phone": "string", "title": "string" } ``` --- ### Customer Status Update Request Customer status update request including close/open flag and reason. **closeCustomer**boolean True to close, false to open. **reason**string Reason if the customer is closed. Customer Status Update Request ```json { "closeCustomer": true, "reason": "string" } ``` --- ### Hosted Payment Methods Payment methods enabled for the payment plugin session. **aliPayPlus**boolean Conditional if mode is set to 0. Show AliPay+ option only if the option is enable for the merchant.Default is false. **applePay**boolean Conditional if mode is set to 0. Show Apple Pay option only if the option is enable for the merchant.Default is false. **bankAccount**boolean Conditional. Required if mode is set to 0 or 2. Show bank account option only if the option is enable for the merchant.Default is false. **card**boolean Conditional. Required if mode is set to 0 or 2. Show card option only if the option is enable for the merchant.Default is true. **cardTokenise**boolean Conditional. Required if mode is set to 0 or 2. Show card tokenise option only if the option is enable for the merchant.Default is true. **googlePay**boolean Conditional if mode is set to 0. Show Google Pay option only if the option is enable for the merchant.Default is false. **latitudePay**boolean Conditional if mode is set to 0. Show Latitude Pay option only if the option is enable for the merchant.Default is false. **payId**boolean Conditional. Required if mode is set to 0 or 2. Show PayID option only if the option is enable for the merchant.Default is false. **payTo**boolean Conditional. Required if mode is set to 0 or 2. Show PayTo option only if the option is enable for the merchant.Default is false. **slicePay**boolean Conditional if mode is set to 0. Show Slice Pay option only if the option is enable for the merchant.Default is false. **unionPay**boolean Conditional if mode is set to 0. Show UnionPay option only if the option is enable for the merchant.Default is false. **weChat**boolean Conditional if mode is set to 0. Show WeChat Pay option only if the option is enable for the merchant.Default is false. Hosted Payment Methods ```json { "aliPayPlus": true, "applePay": true, "bankAccount": true, "card": true, "cardTokenise": true, "googlePay": true, "latitudePay": true, "payId": true, "payTo": true, "slicePay": true, "unionPay": true, "weChat": true } ``` --- ### Hosted Payment Page Customization Visual customization options for the payment plugin. **customerNameLabel**string Custom label to override default customer name display text. **customerReferenceLabel**string Custom label to override default customer reference display text. **hideHeader**boolean Hide the plugin header. Defaults to false if not provided. **hideMerchantLogo**boolean This will hide the merchant logo if any. Defaults to 'false' if not provided. **paymentAmountLabel**string Custom label to override default payment amount display text. **title**string Plugin Title. Defaults to 'Process Payment' if not provided. Hosted Payment Page Customization ```json { "customerNameLabel": "string", "customerReferenceLabel": "string", "hideHeader": true, "hideMerchantLogo": true, "paymentAmountLabel": "string", "title": "string" } ``` --- ### Hosted Payment Session Request Session creation request including payment mode, version, and customization options. **additionalReference**string Additional reference for reconciliation reports. **allowSaveCardInformation**boolean Optional. This will allow to save the card information. Defaults to 'false' if not provided. This option will only work if 'Enable Plugin Pay & Save Card' option is enabled at program or merchant level. **allowedPaymentMethods** object Allowed Payment methods. **aliPayPlus**boolean Conditional if mode is set to 0. Show AliPay+ option only if the option is enable for the merchant.Default is false. **applePay**boolean Conditional if mode is set to 0. Show Apple Pay option only if the option is enable for the merchant.Default is false. **bankAccount**boolean Conditional. Required if mode is set to 0 or 2. Show bank account option only if the option is enable for the merchant.Default is false. **card**boolean Conditional. Required if mode is set to 0 or 2. Show card option only if the option is enable for the merchant.Default is true. **cardTokenise**boolean Conditional. Required if mode is set to 0 or 2. Show card tokenise option only if the option is enable for the merchant.Default is true. **googlePay**boolean Conditional if mode is set to 0. Show Google Pay option only if the option is enable for the merchant.Default is false. **latitudePay**boolean Conditional if mode is set to 0. Show Latitude Pay option only if the option is enable for the merchant.Default is false. **payId**boolean Conditional. Required if mode is set to 0 or 2. Show PayID option only if the option is enable for the merchant.Default is false. **payTo**boolean Conditional. Required if mode is set to 0 or 2. Show PayTo option only if the option is enable for the merchant.Default is false. **slicePay**boolean Conditional if mode is set to 0. Show Slice Pay option only if the option is enable for the merchant.Default is false. **unionPay**boolean Conditional if mode is set to 0. Show UnionPay option only if the option is enable for the merchant.Default is false. **weChat**boolean Conditional if mode is set to 0. Show WeChat Pay option only if the option is enable for the merchant.Default is false. **apiKey**string Set by the plugin. Leave it out of your request. **businessNumber**string Optional. Business Number (For example: ABN). Used for reward programs if the Program is enabled to provide reward points. **callbackUrl**string Optional. The URL will be called with HTTP POST method to submit the result. Refer to Payment Plugin documentation for payment response payload. **companyName**string Optional. Customer company name. **contactNumber**string Optional. Contact number. **customerEmail**string Required. Email address to which invoice will be emailed if the merchant is configured. It is mandatory from V4. **customerName**string Conditional. Required if mode is set to 0 or 2. **customerReference**string Conditional. Required if mode is set to 0 or 2. **customization** object Optional. Fields to customize the plugin fields. **customerNameLabel**string Custom label to override default customer name display text. **customerReferenceLabel**string Custom label to override default customer reference display text. **hideHeader**boolean Hide the plugin header. Defaults to false if not provided. **hideMerchantLogo**boolean This will hide the merchant logo if any. Defaults to 'false' if not provided. **paymentAmountLabel**string Custom label to override default payment amount display text. **title**string Plugin Title. Defaults to 'Process Payment' if not provided. **departureDate**string\ Conditional. DepartureDate is required for Slice Pay. Provide date in UTC ISO 8601 format as departureDate. format: yyyy-MM-dd. **displayMode**integer\required Optional. Must be one of the following two values 0 - Default(Modal) 1 - Redirect Url. Defaults to 0 if not provided. \*Google Pay and Apple Pay works if Modal or Redirect Url with iframe is used. | Enum Value | Description | | ---------- | ----------- | | 0 | Default | | 1 | RedirectUrl | **endpointUrl**stringrequired Endpoint url of the plugin. Just provide the base url. For example: . **fingerprint**string Set by the plugin. Leave it out of your request. **hideTermsAndConditions**boolean Optional. This will hide the Terms and Conditions. Defaults to 'false' if not provided. **isJsPlugin**booleanrequired Is JS Plugin. Default is true. Set to false if you want to use without iframe. **merchantCode**stringrequired Merchant code. Make sure the merchant code is related to the API credentials. **merchantUniquePaymentId**stringrequired Required. Payment id provided by the merchant. Must be unique and can not be reused if a transaction is processed using this id. This field also work as IdempotencyKey for request for successful requests. **mode**integer\required Optional. Must be one of the following three values 0 - Make Payment 1 - Tokenise 2 - Custom Payment 3 - Preauthorization. Defaults to 0 if not provided. | Enum Value | Description | | ---------- | -------------- | | 0 | DefaultPayment | | 1 | Tokenise | | 2 | CustomPayment | | 3 | Preauth | **overrideFeePayer**integer\ Optional. Must be one of the following three values 0 - Default(based on pricing profile) 1 - Merchant(Merchant will pay the fee regardless of pricing profile setting) 2 - Customer(Customer will pay the fee regardless of pricing profile setting) Defaults to 0 if not provided. | Enum Value | Description | | ---------- | ----------- | | 0 | Default | | 1 | Merchant | | 2 | Customer | **paymentAccountProxy**string Conditional. Use this parameter to make a payment using a payment account proxy which is generated using mode '1'. **paymentAmount**number\ Conditional. Required if mode is set to 0 or 2. Returns applicable fee if provided with mode 1. **redirectOnError**boolean All errors/exceptions will be return back the caller using the redirect url. **redirectUrl**stringrequired Required. The page will redirect to this URL with the result in the query string. Refer the return parameters section below. **sendConfirmationEmailToCustomer**boolean Optional. This will send confirmation email to customer. Defaults to 'false' if not provided. **sendConfirmationEmailToMerchant**boolean Optional. This will send confirmation email to merchant. Defaults to 'false' if not provided. **showFailedPaymentFeeOnTokenising**boolean Optional if mode is set to 1. Show the applicable failed payment fees for the token at the end of the process.Default is false. **showFeeOnTokenising**boolean Required if mode is set to 1. Show the applicable fees for the token at the end of the process.Default is false. **sku1**string Optional. Stock Keeping Unit - Optional text fields, allowing up to 50 alphanumeric characters. If the value exceeds 50 characters, only the first 50 characters will be retained and the rest discarded. **sku2**string Optional Stock Keeping Unit - Optional text fields, allowing up to 50 alphanumeric characters. If the value exceeds 50 characters, only the first 50 characters will be retained and the rest discarded. **timestamp**string\required Required. Timestamp is required from v4. Provide current datetime in UTC ISO 8601 format as timestamp. format: yyyy-MM-ddTHH:mm:ss. **Example: **`2025-10-01T02:15:56` **userMode**integer\required Optional. Must be one of the following two values 0 - Customer Facing - default (cardholder must enter CCV or 3DS) 1 - Merchant Facing(for merchant use only - no CCV or 3DS) - if supported by merchant options. | Enum Value | Description | | ---------- | ----------- | | 0 | Customer | | 1 | Merchant | **version**integer\required Required. Plugin version. Always use the latest. | Enum Value | Description | | ---------- | ----------- | | 1 | v1 | | 2 | v2 | | 3 | v3 | | 4 | v4 | | 5 | v5 | Hosted Payment Session Request ```json { "additionalReference": "string", "allowSaveCardInformation": true, "allowedPaymentMethods": { "aliPayPlus": true, "applePay": true, "bankAccount": true, "card": true, "cardTokenise": true, "googlePay": true, "latitudePay": true, "payId": true, "payTo": true, "slicePay": true, "unionPay": true, "weChat": true }, "apiKey": "string", "businessNumber": "string", "callbackUrl": "string", "companyName": "string", "contactNumber": "string", "customerEmail": "string", "customerName": "string", "customerReference": "string", "customization": { "customerNameLabel": "string", "customerReferenceLabel": "string", "hideHeader": true, "hideMerchantLogo": true, "paymentAmountLabel": "string", "title": "string" }, "departureDate": "2024-07-29T15:51:28.071Z", "displayMode": 0, "endpointUrl": "string", "fingerprint": "string", "hideTermsAndConditions": true, "isJsPlugin": true, "merchantCode": "string", "merchantUniquePaymentId": "string", "mode": 0, "overrideFeePayer": 0, "paymentAccountProxy": "string", "paymentAmount": 0, "redirectOnError": true, "redirectUrl": "string", "sendConfirmationEmailToCustomer": true, "sendConfirmationEmailToMerchant": true, "showFailedPaymentFeeOnTokenising": true, "showFeeOnTokenising": true, "sku1": "string", "sku2": "string", "timestamp": "2025-10-01T02:15:56", "userMode": 0, "version": 1 } ``` --- ### Hosted Payment Session Response Session response containing the secure token, expiry, and payment plugin endpoint URL. **endpointUrl**string Payment plugin endpoint url. **expiresAt**string\ Expiry of the secure token. **secureToken**string Token used to initialize the payment plugin. Hosted Payment Session Response ```json { "endpointUrl": "string", "expiresAt": "2024-07-29T15:51:28.071Z", "secureToken": "string" } ``` --- ### Internal Server Error Response returned when an internal server error occurs (HTTP 500). **request**object Gets the request message which led to this result. Internal Server Error ```json { "request": {} } ``` --- ### New Customer Request Customer creation request including profile, payment option, and account details. **abn**string Australian Business Number. **additionalPaymentAccountProxies** object\[] Additional PaymentAccountProxies. Proxy is generated using the Payments Plugin for Bank and Credit/Debit Card or /cardProxies api for Credit/Debit Card. * Array \[ **label**string Label for the account. **Max length:** `<= 80 characters` **proxy**stringrequired Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies api for card. **Max length:** `<= 40 characters` * ] **additionalReferences** object\[] Additional references if you have more than one references to manage. Eg: Parents paying childcare fee for more than one kid. * Array \[ **customerReference**string Customer reference linked to this additional reference. **fullName**string Full name associated with the additional reference. * ] **address** object Customer address. **address1**stringrequired Address line 1. **address2**string Address line 2. **country**stringrequired Country. **Max length:** `<= 100 characters` **postcode**stringrequired Postcode. **state**stringrequired State / province. **Max length:** `<= 50 characters` **suburb**stringrequired Suburb / city. **Max length:** `<= 50 characters` **bankAccount** object Customer bank account details. **accountName**stringrequired Account Holder name. **Constraints:** `<= 32 characters`, Value must match regular expression `[\u0020-\u007E]*` **accountNumber**stringrequired Bank Account number. **Format:** Value must match regular expression `^([0-9]{4,10})` **bankBranch**string Bank branch. **Max length:** `<= 50 characters` **bankName**string Bank Name. **Max length:** `<= 50 characters` **bsb**stringrequired BSB Number. Format: 000000. **Max length:** `<= 6 characters` **isPayTo**boolean Bank account is PayTo if true. **label**string Label for the account. **Max length:** `<= 50 characters` **payToStatus**integer\ If PayTo account, this field will let you know the status of the Mandate. **Possible values:** \[`0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`] **card** object Customer credit / debit card proxy. (Token is generated using the /tokens api. **cardProxy**stringrequired Card proxy generated by the /cardproxies api. **Max length:** `<= 40 characters` **label**string Label for the card. **Max length:** `<= 80 characters` **customerCompanyName**string Company name if this is company account. **customerReference**stringrequired Customer / Parent Reference. Should be unique and provided by the merchant. If you are paying the merchant by BPAY, this should be your BPAY Reference. **dateOfBirth**string\required Date of birth. Customer must be atleast 16 years old. **email**stringrequired Email address. **enableBPayOption**boolean Allows to enable BPAY option for the customer / parent. **fax**string Fax number. **firstName**stringrequired First name. **Max length:** `<= 30 characters` **isBPayCrnPassed**boolean Send this as true when customer reference passed if CRN. Default is set to false if not passed. **lastName**stringrequired Last name. **Max length:** `<= 30 characters` **merchantStaffMember**string Merchant Staff member assigned to this customer / parent. **mobile**stringrequired Mobile number. **notificationMethod**integer\required Notification method used to indicate the communication channel when payment successful or failed. | Enum Value | Description | | ---------- | ----------- | | 0 | None | | 1 | Sms | | 2 | Email | **paymentAccountProxy** object This replaces the BankAccount and Card properties. Proxy is generated using the Payments Plugin for Bank and Credit/Debit Card or /cardProxies api for Credit/Debit Card. **label**string Label for the account. **Max length:** `<= 80 characters` **proxy**stringrequired Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies api for card. **Max length:** `<= 40 characters` **paymentAmount**number\required Payment amount. Set the default amount for auto payments or amount for one-off payment. **paymentEndDate**string\ Payment end date. **paymentFrequency**integer\required Payment frequency. Applicable to auto pay, email reminder and sms reminder. | Enum Value | Description | | ---------- | ----------- | | 32 | Weekly | | 33 | Fortnightly | | 34 | Quarterly | | 35 | HalfYearly | | 36 | Yearly | | 37 | FourWeeks | | 38 | Monthly | **paymentOption**integer\required Payment option. Use the correct payment option which is supported by the merchant. | Enum Value | Description | | ---------- | ------------- | | 22 | AutoPay | | 23 | EmailReminder | | 24 | SmsReminder | | 25 | FixedTerm | | 26 | BatchPay | | 27 | ScheduledPay | | 28 | OneOff | | 148 | PayID | | 149 | BPAY | **paymentStartDate**string\required Payment start date. **phone**string Phone number. **promotionCode**string Promotion code if any. **sendWelcomeEmail**boolean Sends welcome email if set to true. Default is set to true if not passed. **title**string Provide the salutation. Eg: Mr or Mrs. **Max length:** `<= 10 characters` **websiteUrl**string Website URL if any. New Customer Request ```json { "abn": "string", "additionalPaymentAccountProxies": [ { "label": "string", "proxy": "string" } ], "additionalReferences": [ { "customerReference": "string", "fullName": "string" } ], "address": { "address1": "string", "address2": "string", "country": "string", "postcode": "string", "state": "string", "suburb": "string" }, "bankAccount": { "accountName": "string", "accountNumber": "string", "bankBranch": "string", "bankName": "string", "bsb": "string", "isPayTo": true, "label": "string", "payToStatus": 0 }, "card": { "cardProxy": "string", "label": "string" }, "customerCompanyName": "string", "customerReference": "string", "dateOfBirth": "2024-07-29T15:51:28.071Z", "email": "string", "enableBPayOption": true, "fax": "string", "firstName": "string", "isBPayCrnPassed": true, "lastName": "string", "merchantStaffMember": "string", "mobile": "string", "notificationMethod": 0, "paymentAccountProxy": { "label": "string", "proxy": "string" }, "paymentAmount": 0, "paymentEndDate": "2024-07-29T15:51:28.071Z", "paymentFrequency": 32, "paymentOption": 22, "paymentStartDate": "2024-07-29T15:51:28.071Z", "phone": "string", "promotionCode": "string", "sendWelcomeEmail": true, "title": "string", "websiteUrl": "string" } ``` --- ### PayID Detail PayID details including PayID value, name, and reference. **payId**string PayID. **payIdName**string PayID Name. **reference**string Reference. PayID Detail ```json { "payId": "string", "payIdName": "string", "reference": "string" } ``` --- ### Payment Account Reference Payment account proxy reference. Recommended over CardProxy. **label**string Label for the account. **Max length:** `<= 80 characters` **proxy**stringrequired Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies api for card. **Max length:** `<= 40 characters` Payment Account Reference ```json { "label": "string", "proxy": "string" } ``` --- ### Payment Account Reference Response Payment account proxy response representing the different response structures for card, bank account, PayID, and PayTo details. **accountName**string Account name (Bank/PayTo accounts). **Example: **`John Smith` **accountNumber**string Account number (Bank/PayTo accounts). **Example: **`12345678` **accountType**string Type of payment account. **Example: **`Card` **bsb**string BSB code (Bank/PayTo accounts). **Example: **`123-456` **cardExpiry**string Card expiry date (Card accounts only). **Example: **`12/25` **cardHolderName**string Card holder name (Card accounts only). **Example: **`John Smith` **cardNumber**string Masked card number (Card accounts only). **Example: **`****1234` **cardType**string Card type (Card accounts only). **Example: **`Visa` **payId**string PayId identifier (PayId accounts only). **Example: **`john.smith@email.com` **payIdName**string PayId display name (PayId accounts only). **Example: **`John Smith` **payToStatus**string PayTo status (PayTo accounts only). **Example: **`Active` **processor3DSPayload**string 3DS payload (Card accounts only). **Example: **`eyJhbGciOiJIUzI1NiJ9...` **processorName**string Processor name (Card accounts only). **Example: **`Stripe` **processorToken**string Processor token (Card accounts only). **Example: **`tok_1234567890` **statusDescription**string Status description (PayTo accounts only). **Example: **`Account is active and ready for payments` **uId**string Unique identifier (PayTo accounts only). **Example: **`12345678-1234-5678-9012-123456789012` Payment Account Reference Response ```json { "accountName": "John Smith", "accountNumber": "12345678", "accountType": "Card", "bsb": "123-456", "cardExpiry": "12/25", "cardHolderName": "John Smith", "cardNumber": "****1234", "cardType": "Visa", "payId": "john.smith@email.com", "payIdName": "John Smith", "payToStatus": "Active", "processor3DSPayload": "eyJhbGciOiJIUzI1NiJ9...", "processorName": "Stripe", "processorToken": "tok_1234567890", "statusDescription": "Account is active and ready for payments", "uId": "12345678-1234-5678-9012-123456789012" } ``` --- ### Payment Additional Data Acquirer and issuer references for a card transaction: the authorisation code, the retrieval reference number and the system trace audit number. **authCode**string Authorisation code returned by the card issuer. **rrn**string Retrieval reference number assigned by the acquirer, used when tracing the transaction with them. **stan**string System trace audit number identifying the transaction on the acquirer's network. Payment Additional Data ```json { "authCode": "string", "rrn": "string", "stan": "string" } ``` --- ### Payment Card Card details for direct card payment including cardholder name, card number, expiry, and CVV. **cardHolder**stringrequired Name of the cardholder. **cardNumber**stringrequired Card number. **cvv**stringrequired Card verification value. **expiryMonth**stringrequired Card expiry month. **expiryYear**stringrequired Card expiry year. **Length:** `>= 4 characters` and `<= 4 characters` Payment Card ```json { "cardHolder": "string", "cardNumber": "string", "cvv": "string", "expiryMonth": "string", "expiryYear": "string" } ``` --- ### Payment Request Payment request including customer reference or card proxy, amount, and optional 3D Secure details. **abn**string Customer Australian Business Number. **additionalReference**string Additional reference. This field is returned in reconciliation reports. **card** object PAN detail. **cardHolder**stringrequired Name of the cardholder. **cardNumber**stringrequired Card number. **cvv**stringrequired Card verification value. **expiryMonth**stringrequired Card expiry month. **expiryYear**stringrequired Card expiry year. **Length:** `>= 4 characters` and `<= 4 characters` **cardProxy**string Card Proxy (Conditional). Use only if you want to pay using card proxy. **companyName**string Customer company name. **contactNumber**string Customer contact number. **customerEmail**string The customer email to which an invoice is sent to. **customerName**string Customer name. **customerReference**stringrequired Customer reference. Required only when payment account proxy or card proxy is not provided. **merchantUniquePaymentId**string Unique payment id provided by the merchant. **Max length:** `<= 50 characters` **oneOffPaymentReference**string One Off Payment reference. This field is returned in reconciliation reports. **overrideFeePayer**integer\required Override Fee Payer. This field is to determine who is paying transaction fee. 0 Use Set Profile - default 1 Merchant Pays Fee (if allowed) 2 Customer Pays Fee (if allowed). | Enum Value | Description | | ---------- | ----------- | | 0 | Default | | 1 | Merchant | | 2 | Customer | **paymentAccountProxy** object Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies API for card. **label**string Label for the account. **Max length:** `<= 80 characters` **proxy**stringrequired Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies api for card. **Max length:** `<= 40 characters` **paymentAmount**number\required Payment amount. **sendPaymentConfirmation**boolean Flag to send the customer invoice. **threeDSecureData** object Optional. 3DSecure details. **browserData** object Cardholder's browser data. Mandatory if UseThreeDSecure is true. **acceptHeader**string Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser. **colorDepth**integer\ Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. Possible values: 1, 4, 8, 15, 16, 24, 32, 48. **ipAddress**string IP address of the browser as returned by the HTTP headers to the 3DS Requestor. **language**string Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters. Value is returned from navigator.language property. **screenHeight**integer\ Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property. **screenWidth**integer\ Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property. **timezone**string Time difference between UTC time and the Cardholder browser local time, in minutes. The field is limited to 1-5 characters where the value is returned from the getTimezoneOffset() method. **userAgent**string Exact content of the HTTP user-agent header. The field is limited to maximum 2048 characters. Obtained from Cardholder browser using the navigator.userAgent property. **callbackUrl**string Endpoint to receive status notifications once 3DSecure is completed. Use \[uniqueId] (case sensitive) in URL to differentiate different payments and 3DS statuses For example: CallbackUrl [https://www.yourdomain.com.au/3dsecure/\[uniqueId](https://www.yourdomain.com.au/3dsecure/%5BuniqueId)] will be translated to assuming uniqueId is 123456. **redirectUrl**string Redirect URL used to redirect once the 3DSecure process is completed. Use \[uniqueId], \[status] (case sensitive) in URL to differentiate different payments and 3DS statuses For example: RedirectUrl [https://www.yourdomain.com.au/3dsecure/\[uniqueId\]?status=\[status](https://www.yourdomain.com.au/3dsecure/%5BuniqueId%5D?status=%5Bstatus)] will be translated to assuming uniqueId is 123456 Possible 3DSecure statuses: Success, Failed, Cancelled. **useThreeDSecure**boolean Will trigger 3DSecure process if enabled or valid for the card. Payment Request ```json { "abn": "string", "additionalReference": "string", "card": { "cardHolder": "string", "cardNumber": "string", "cvv": "string", "expiryMonth": "string", "expiryYear": "string" }, "cardProxy": "string", "companyName": "string", "contactNumber": "string", "customerEmail": "string", "customerName": "string", "customerReference": "string", "merchantUniquePaymentId": "string", "oneOffPaymentReference": "string", "overrideFeePayer": 0, "paymentAccountProxy": { "label": "string", "proxy": "string" }, "paymentAmount": 0, "sendPaymentConfirmation": true, "threeDSecureData": { "browserData": { "acceptHeader": "string", "colorDepth": 0, "ipAddress": "string", "language": "string", "screenHeight": 0, "screenWidth": 0, "timezone": "string", "userAgent": "string" }, "callbackUrl": "string", "redirectUrl": "string", "useThreeDSecure": true } } ``` --- ### Payment Result Payment response including status, amounts, fees, and settlement details. Fields marked as conditional are only returned under certain conditions. **abn**string ABN for the transaction. **accountOrCardNo**string Payment Card No. **additionalData** object Acquirer and issuer references for the transaction, returned for card payments. **authCode**string Authorisation code returned by the card issuer. **rrn**string Retrieval reference number assigned by the acquirer, used when tracing the transaction with them. **stan**string System trace audit number identifying the transaction on the acquirer's network. **additionalReference**string Additional reference. (Conditional). **baseAmount**number\ Base amount of the payment is done. **cardCategory**string Card category. **cardTypeString**string Card scheme the payment was processed on, as text. For example: MasterCard. **cardTypeValue**integer\ Card scheme the payment was processed on, as its numeric code. Pairs with `cardTypeString`. **chargeBackedOn**string\ Recalled date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **chargeBackedReason**string Reason. (Conditional). **chargeBackedTransactionReference**string ChargedBackedTransactionReference : If a charge transaction is charged back then this is transaction reference of charged back transaction.(Conditional). **chargebacks** object\[] All chargebacks processed on this payment. * Array \[ **customerFee**number\ Fee charged on Customer. **merchantFee**number\ Fee charged on Merchant. **paymentAmount**number\ Total payment amount including the fees. **processedOn**string\ Refund/Recall date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **reason**string Reason. (Conditional). **status**string Current Status of the refund/recall. Expected Statuses 1. Pending This refund/recall is waiting be to processed 2. Error - This refund/recall has encountered an Error 3. Submitted - This refund/recall was successfully submitted 4. Successful - This refund/recall was successful 5. Failed - This refund/recall has Failed 6. Cancelled - This refund/recall was Cancelled 7. Suppressed - This refund/recall was Suppressed 8. InProgress - This refund/recall is being processed. **transactionReference**string TransactionReference : If a charge transaction is refunded/recalled then this is transaction reference of that transaction.(Conditional). * ] **customerCode**string Unique customer code if the customer exists in the system. **customerFee**number\ Fee charged on customer card. **customerName**string Customer who paid the payment. **customerReference**string Reference of the Customer who paid the payment. **failureCode**string Failure code if the payment failed. Please refer: for more details. (Conditional). **failureReason**string Failure reason if the payment failed. (Conditional). **fundsToMerchant**number\ Funds to Merchant. **isPaymentChargeBacked**boolean Payment Charge Backed. **isPaymentRecalled**boolean Payment recalled. **isPaymentRefunded**boolean Payment refunded. **isPaymentRetryScheduled**boolean Whether a retry payment is pending. Based on Program/Merchant settings, a failed payment will be retried. **isPaymentSettledToMerchant**boolean Whether the payment has been settled to the merchant. **merchantCode**string Merchant code. **merchantFee**number\ Fee charged on Merchant. **merchantName**string Merchant trading name. **merchantSettlementReference**string Reference for the merchant settlement this payment was paid out in. Empty until the payment settles. **merchantUniquePaymentId**string Unique payment id provided by the merchant. (Conditional). **oneOffPaymentReference**string One Off Payment Reference. **originalTransactionReference**string OriginalTransactionReference : For a Recall / Refund transaction, it is the transaction reference of original transaction. **paymentAccount**string Payment Account by which the payment is done. **paymentAmount**number\ Total payment amount including the fees. **paymentCard**string Payment card used. **paymentReference**string Unique Payment Reference for the payment done. **paymentSourceDisplay**string Payment source of transaction. **paymentStatus**string Current Status of the payment. Expected Statuses 1. Pending This Payment is waiting be to processed 2. Error - This Payment has encountered an Error 3. Submitted - This Payment was successfully submitted 4. Successful - This Payment was successful 5. Successful(Recalled) - This Payment was Recalled 6. Successful(Refunded) - This Payment was Refunded 7. Successful (Refunded) (Recalled) - This Payment was Refunded and Recalled 8. Failed - This Payment has Failed 9. Cancelled - This Payment was Cancelled 10. Suppressed - This Payment was Suppressed 11. InProgress - This Payment is being processed. **preauthExpiryAt**string\ Preauth expiry in minutes. **processingDate**string\ Processing Date for the payment. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST. **processorReference**string Processor reference for the payment done. **recalledOn**string\ Recalled date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **recalledReason**string Reason. (Conditional). **recalledTransactionReference**string RecalledTransactionReference : If a charge transaction is recalled then this is transaction reference of recall transaction.(Conditional). **recalls** object\[] All recalls processed on this payment. * Array \[ **customerFee**number\ Fee charged on Customer. **merchantFee**number\ Fee charged on Merchant. **paymentAmount**number\ Total payment amount including the fees. **processedOn**string\ Refund/Recall date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **reason**string Reason. (Conditional). **status**string Current Status of the refund/recall. Expected Statuses 1. Pending This refund/recall is waiting be to processed 2. Error - This refund/recall has encountered an Error 3. Submitted - This refund/recall was successfully submitted 4. Successful - This refund/recall was successful 5. Failed - This refund/recall has Failed 6. Cancelled - This refund/recall was Cancelled 7. Suppressed - This refund/recall was Suppressed 8. InProgress - This refund/recall is being processed. **transactionReference**string TransactionReference : If a charge transaction is refunded/recalled then this is transaction reference of that transaction.(Conditional). * ] **redirectUrl**string 3DSecure redirect url to complete the 3DSecure challege if required by the scheme. **refundedOn**string\ Refunded date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **refundedReason**string Reason. (Conditional). **refundedTransactionReference**string RefundedTransactionReference : If a charge transaction is refunded then this is transaction reference of refunded transaction.(Conditional). **refunds** object\[] All refunds processed on this payment. * Array \[ **customerFee**number\ Fee charged on Customer. **merchantFee**number\ Fee charged on Merchant. **paymentAmount**number\ Total payment amount including the fees. **processedOn**string\ Refund/Recall date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **reason**string Reason. (Conditional). **status**string Current Status of the refund/recall. Expected Statuses 1. Pending This refund/recall is waiting be to processed 2. Error - This refund/recall has encountered an Error 3. Submitted - This refund/recall was successfully submitted 4. Successful - This refund/recall was successful 5. Failed - This refund/recall has Failed 6. Cancelled - This refund/recall was Cancelled 7. Suppressed - This refund/recall was Suppressed 8. InProgress - This refund/recall is being processed. **transactionReference**string TransactionReference : If a charge transaction is refunded/recalled then this is transaction reference of that transaction.(Conditional). * ] **remainingPreauthAmount**number\ Remaining preauth amount. **retryPaymentReference**string Retry payment reference. (Conditional). **retryScheduledOn**string\ Retry payment scheduled date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **settlementDate**string\ Settlement Date for the payment. This is a calculated date and may change until the payment been settled. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST. **settlementFrequencyString**string How often the merchant is settled, as text. For example: Monthly. **settlementFrequencyValue**integer\ How often the merchant is settled, as its numeric code. Pairs with `settlementFrequencyString`. **settlementPostPartialRefund** object Balance Payment if any is available. **fundsToMerchant**number\ Amount to be settled to the merchant. **merchantSettlementDate**string\ Date payment will be settled to the merchant. **processedOn**string\ Processing date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST. **status**string Current Status of the balance payment. Expected Statuses 1. Pending 2. Error 3. Submitted 4. Successful 5. Failed 6. Cancelled 7. Suppressed 8. InProgress. **transactionReference**string TransactionReference. **settlementReference**string Reference for the settlement this payment was paid out in. Empty until the payment settles. **settlementType**string Whether the merchant is settled gross or net of fees. For example: Gross. **sku1**string Stock keeping unit field 1. **sku2**string Stock keeping unit field 2. **subCardType**string Sub card type. **subCardTypeString**string Card sub-type where the scheme has one, as text. Empty when the scheme has none. **subCardTypeValue**integer\ Card sub-type as its numeric code. Pairs with `subCardTypeString`. **transactionType**integer\ Transaction type numeric code. | Enum Value | Description | | ---------- | ----------------------------------- | | 1 | Charge | | 2 | InvoicePayment | | 3 | Refund | | 4 | Chargeback | | 5 | Recall | | 6 | FixedTermSettlement | | 7 | SponsorInvoicePayment | | 8 | MerchantSettlementAdjustmentPayment | | 9 | Preauthorization | | 10 | Credit | **transactionTypeDisplay**string Transaction Type. Possible values: 1. Charge 2. Invoice 3. Refund 4. Chargeback 5. Recall 6. Fixed Term Settlement. Payment Result ```json { "abn": "string", "accountOrCardNo": "string", "additionalData": { "authCode": "string", "rrn": "string", "stan": "string" }, "additionalReference": "string", "baseAmount": 0, "cardCategory": "string", "cardTypeString": "string", "cardTypeValue": 0, "chargeBackedOn": "2024-07-29T15:51:28.071Z", "chargeBackedReason": "string", "chargeBackedTransactionReference": "string", "chargebacks": [ { "customerFee": 0, "merchantFee": 0, "paymentAmount": 0, "processedOn": "2024-07-29T15:51:28.071Z", "reason": "string", "status": "string", "transactionReference": "string" } ], "customerCode": "string", "customerFee": 0, "customerName": "string", "customerReference": "string", "failureCode": "string", "failureReason": "string", "fundsToMerchant": 0, "isPaymentChargeBacked": true, "isPaymentRecalled": true, "isPaymentRefunded": true, "isPaymentRetryScheduled": true, "isPaymentSettledToMerchant": true, "merchantCode": "string", "merchantFee": 0, "merchantName": "string", "merchantSettlementReference": "string", "merchantUniquePaymentId": "string", "oneOffPaymentReference": "string", "originalTransactionReference": "string", "paymentAccount": "string", "paymentAmount": 0, "paymentCard": "string", "paymentReference": "string", "paymentSourceDisplay": "string", "paymentStatus": "string", "preauthExpiryAt": "2024-07-29T15:51:28.071Z", "processingDate": "2024-07-29T15:51:28.071Z", "processorReference": "string", "recalledOn": "2024-07-29T15:51:28.071Z", "recalledReason": "string", "recalledTransactionReference": "string", "recalls": [ { "customerFee": 0, "merchantFee": 0, "paymentAmount": 0, "processedOn": "2024-07-29T15:51:28.071Z", "reason": "string", "status": "string", "transactionReference": "string" } ], "redirectUrl": "string", "refundedOn": "2024-07-29T15:51:28.071Z", "refundedReason": "string", "refundedTransactionReference": "string", "refunds": [ { "customerFee": 0, "merchantFee": 0, "paymentAmount": 0, "processedOn": "2024-07-29T15:51:28.071Z", "reason": "string", "status": "string", "transactionReference": "string" } ], "remainingPreauthAmount": 0, "retryPaymentReference": "string", "retryScheduledOn": "2024-07-29T15:51:28.071Z", "settlementDate": "2024-07-29T15:51:28.071Z", "settlementFrequencyString": "string", "settlementFrequencyValue": 0, "settlementPostPartialRefund": { "fundsToMerchant": 0, "merchantSettlementDate": "2024-07-29T15:51:28.071Z", "processedOn": "2024-07-29T15:51:28.071Z", "status": "string", "transactionReference": "string" }, "settlementReference": "string", "settlementType": "string", "sku1": "string", "sku2": "string", "subCardType": "string", "subCardTypeString": "string", "subCardTypeValue": 0, "transactionType": 1, "transactionTypeDisplay": "string" } ``` --- ### Ping Response Ping response including server date time and version information. **buildVersion**string Build version. **serverDateTime**string\ Server Date Time. **timeZoneInfo**string DateTime Time Zone. **version**string API version. Ping Response ```json { "buildVersion": "string", "serverDateTime": "2024-07-29T15:51:28.071Z", "timeZoneInfo": "string", "version": "string" } ``` --- ### Preauthorization Capture Request Capture request for a preauthorization including payment amount and optional references. **additionalReference**string Additional reference. This field is returned in reconciliation reports. **merchantUniquePaymentId**string Unique payment id provided by the merchant. **Max length:** `<= 50 characters` **oneOffPaymentReference**string One Off Payment reference. This field is returned in reconciliation reports. **paymentAmount**number\required Amount to capture. **sendPaymentConfirmation**boolean Flag to send the customer invoice. Preauthorization Capture Request ```json { "additionalReference": "string", "merchantUniquePaymentId": "string", "oneOffPaymentReference": "string", "paymentAmount": 0, "sendPaymentConfirmation": true } ``` --- ### Preauthorization Capture Result Capture preauthorization response including status, amounts, and transaction details. Fields marked as conditional are only returned under certain conditions. **abn**string ABN for the transaction. **accountOrCardNo**string Payment Card No. **additionalReference**string Additional reference. (Conditional). **baseAmount**number\ Base amount of the payment is done. **cardCategory**string Card category. **chargeBackedOn**string\ Recalled date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **chargeBackedReason**string Reason. (Conditional). **chargeBackedTransactionReference**string ChargedBackedTransactionReference : If a charge transaction is charged back then this is transaction reference of charged back transaction.(Conditional). **customerFee**number\ Fee charged on customer card. **customerName**string Customer who paid the payment. **customerReference**string Reference of the Customer who paid the payment. **failureCode**string Failure code if the payment failed. Please refer: for more details. (Conditional). **failureReason**string Failure reason if the payment failed. (Conditional). **fundsToMerchant**number\ Funds to Merchant. **isPaymentChargeBacked**boolean Payment Charge Backed. **isPaymentRecalled**boolean Payment recalled. **isPaymentRefunded**boolean Payment refunded. **isPaymentRetryScheduled**boolean Whether a retry payment is pending. Based on Program/Merchant settings, a failed payment will be retried. **isPaymentSettledToMerchant**boolean Whether the payment has been settled to the merchant. **merchantCode**string Merchant code. **merchantFee**number\ Fee charged on Merchant. **merchantName**string Merchant trading name. **merchantUniquePaymentId**string Unique payment id provided by the merchant. (Conditional). **oneOffPaymentReference**string One Off Payment Reference. **originalTransactionReference**string OriginalTransactionReference : For a Recall / Refund transaction, it is the transaction reference of original transaction. **paymentAccount**string Payment Account by which the payment is done. **paymentAmount**number\ Total payment amount including the fees. **paymentCard**string Payment card used. **paymentReference**string Unique Payment Reference for the payment done. **paymentSourceDisplay**string Payment source of transaction. **paymentStatus**string Current Status of the payment. Expected Statuses 1. Pending This Payment is waiting be to processed 2. Error - This Payment has encountered an Error 3. Submitted - This Payment was successfully submitted 4. Successful - This Payment was successful 5. Successful(Recalled) - This Payment was Recalled 6. Successful(Refunded) - This Payment was Refunded 7. Successful (Refunded) (Recalled) - This Payment was Refunded and Recalled 8. Failed - This Payment has Failed 9. Cancelled - This Payment was Cancelled 10. Suppressed - This Payment was Suppressed 11. InProgress - This Payment is being processed. **preauthExpiryAt**string\ Preauth expiry in minutes. **processingDate**string\ Processing Date for the payment. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST. **processorReference**string Processor reference for the payment done. **recalledOn**string\ Recalled date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **recalledReason**string Reason. (Conditional). **recalledTransactionReference**string RecalledTransactionReference : If a charge transaction is recalled then this is transaction reference of recall transaction.(Conditional). **refundedOn**string\ Refunded date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **refundedReason**string Reason. (Conditional). **refundedTransactionReference**string RefundedTransactionReference : If a charge transaction is refunded then this is transaction reference of refunded transaction.(Conditional). **remainingPreauthAmount**number\ Remaining preauth amount after one or more captures. **retryPaymentReference**string Retry payment reference. (Conditional). **retryScheduledOn**string\ Retry payment scheduled date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **settlementDate**string\ Settlement Date for the payment. This is a calculated date and may change until the payment been settled. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST. **transactionType**integer\ Transaction type numeric code. | Enum Value | Description | | ---------- | ----------------------------------- | | 1 | Charge | | 2 | InvoicePayment | | 3 | Refund | | 4 | Chargeback | | 5 | Recall | | 6 | FixedTermSettlement | | 7 | SponsorInvoicePayment | | 8 | MerchantSettlementAdjustmentPayment | | 9 | Preauthorization | | 10 | Credit | **transactionTypeDisplay**string Transaction Type. Possible values: 1. Charge 2. Invoice 3. Refund 4. Chargeback 5. Recall 6. Fixed Term Settlement. Preauthorization Capture Result ```json { "abn": "string", "accountOrCardNo": "string", "additionalReference": "string", "baseAmount": 0, "cardCategory": "string", "chargeBackedOn": "2024-07-29T15:51:28.071Z", "chargeBackedReason": "string", "chargeBackedTransactionReference": "string", "customerFee": 0, "customerName": "string", "customerReference": "string", "failureCode": "string", "failureReason": "string", "fundsToMerchant": 0, "isPaymentChargeBacked": true, "isPaymentRecalled": true, "isPaymentRefunded": true, "isPaymentRetryScheduled": true, "isPaymentSettledToMerchant": true, "merchantCode": "string", "merchantFee": 0, "merchantName": "string", "merchantUniquePaymentId": "string", "oneOffPaymentReference": "string", "originalTransactionReference": "string", "paymentAccount": "string", "paymentAmount": 0, "paymentCard": "string", "paymentReference": "string", "paymentSourceDisplay": "string", "paymentStatus": "string", "preauthExpiryAt": "2024-07-29T15:51:28.071Z", "processingDate": "2024-07-29T15:51:28.071Z", "processorReference": "string", "recalledOn": "2024-07-29T15:51:28.071Z", "recalledReason": "string", "recalledTransactionReference": "string", "refundedOn": "2024-07-29T15:51:28.071Z", "refundedReason": "string", "refundedTransactionReference": "string", "remainingPreauthAmount": 0, "retryPaymentReference": "string", "retryScheduledOn": "2024-07-29T15:51:28.071Z", "settlementDate": "2024-07-29T15:51:28.071Z", "transactionType": 1, "transactionTypeDisplay": "string" } ``` --- ### Preauthorization Request Preauthorization request including customer reference, amount, and optional card or proxy details. **abn**string Customer Australian Business Number. **additionalReference**string Additional reference. This field is returned in reconciliation reports. **card** object PAN detail. **cardHolder**stringrequired Name of the cardholder. **cardNumber**stringrequired Card number. **cvv**stringrequired Card verification value. **expiryMonth**stringrequired Card expiry month. **expiryYear**stringrequired Card expiry year. **Length:** `>= 4 characters` and `<= 4 characters` **cardProxy**string Card Proxy (Conditional). Use only if you want to pay using card proxy. **companyName**string Customer company name. **contactNumber**string Customer contact number. **customerEmail**string The customer email to which an invoice is sent to. **customerName**string Customer name. **customerReference**stringrequired Customer reference. Required only when payment account proxy or card proxy is not provided. **merchantUniquePaymentId**string Unique payment id provided by the merchant. **Max length:** `<= 50 characters` **oneOffPaymentReference**string One Off Payment reference. This field is returned in reconciliation reports. **overrideFeePayer**integer\ Override Fee Payer. This field is to determine who is paying transaction fee. 0 Use Set Profile - default 1 Merchant Pays Fee (if allowed) 2 Customer Pays Fee (if allowed). | Enum Value | Description | | ---------- | ----------- | | 0 | Default | | 1 | Merchant | | 2 | Customer | **paymentAccountProxy** object Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies API for card. **label**string Label for the account. **Max length:** `<= 80 characters` **proxy**stringrequired Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies api for card. **Max length:** `<= 40 characters` **preauthAmount**number\required Preauth amount. **threeDSecureData** object Optional. 3DSecure details. **browserData** object Cardholder's browser data. Mandatory if UseThreeDSecure is true. **acceptHeader**string Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser. **colorDepth**integer\ Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. Possible values: 1, 4, 8, 15, 16, 24, 32, 48. **ipAddress**string IP address of the browser as returned by the HTTP headers to the 3DS Requestor. **language**string Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters. Value is returned from navigator.language property. **screenHeight**integer\ Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property. **screenWidth**integer\ Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property. **timezone**string Time difference between UTC time and the Cardholder browser local time, in minutes. The field is limited to 1-5 characters where the value is returned from the getTimezoneOffset() method. **userAgent**string Exact content of the HTTP user-agent header. The field is limited to maximum 2048 characters. Obtained from Cardholder browser using the navigator.userAgent property. **callbackUrl**string Endpoint to receive status notifications once 3DSecure is completed. Use \[uniqueId] (case sensitive) in URL to differentiate different payments and 3DS statuses For example: CallbackUrl [https://www.yourdomain.com.au/3dsecure/\[uniqueId](https://www.yourdomain.com.au/3dsecure/%5BuniqueId)] will be translated to assuming uniqueId is 123456. **redirectUrl**string Redirect URL used to redirect once the 3DSecure process is completed. Use \[uniqueId], \[status] (case sensitive) in URL to differentiate different payments and 3DS statuses For example: RedirectUrl [https://www.yourdomain.com.au/3dsecure/\[uniqueId\]?status=\[status](https://www.yourdomain.com.au/3dsecure/%5BuniqueId%5D?status=%5Bstatus)] will be translated to assuming uniqueId is 123456 Possible 3DSecure statuses: Success, Failed, Cancelled. **useThreeDSecure**boolean Will trigger 3DSecure process if enabled or valid for the card. Preauthorization Request ```json { "abn": "string", "additionalReference": "string", "card": { "cardHolder": "string", "cardNumber": "string", "cvv": "string", "expiryMonth": "string", "expiryYear": "string" }, "cardProxy": "string", "companyName": "string", "contactNumber": "string", "customerEmail": "string", "customerName": "string", "customerReference": "string", "merchantUniquePaymentId": "string", "oneOffPaymentReference": "string", "overrideFeePayer": 0, "paymentAccountProxy": { "label": "string", "proxy": "string" }, "preauthAmount": 0, "threeDSecureData": { "browserData": { "acceptHeader": "string", "colorDepth": 0, "ipAddress": "string", "language": "string", "screenHeight": 0, "screenWidth": 0, "timezone": "string", "userAgent": "string" }, "callbackUrl": "string", "redirectUrl": "string", "useThreeDSecure": true } } ``` --- ### Preauthorization Result Preauthorization response including status, amounts, fees, and settlement details. Fields marked as conditional are only returned under certain conditions. **abn**string ABN for the transaction. **accountOrCardNo**string Payment Card No. **additionalReference**string Additional reference. (Conditional). **baseAmount**number\ Base amount of the payment is done. **cardCategory**string Card category. **chargeBackedOn**string\ Recalled date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **chargeBackedReason**string Reason. (Conditional). **chargeBackedTransactionReference**string ChargedBackedTransactionReference : If a charge transaction is charged back then this is transaction reference of charged back transaction.(Conditional). **customerFee**number\ Fee charged on customer card. **customerName**string Customer who paid the payment. **customerReference**string Reference of the Customer who paid the payment. **failureCode**string Failure code if the payment failed. Please refer: for more details. (Conditional). **failureReason**string Failure reason if the payment failed. (Conditional). **fundsToMerchant**number\ Funds to Merchant. **isPaymentChargeBacked**boolean Payment Charge Backed. **isPaymentRecalled**boolean Payment recalled. **isPaymentRefunded**boolean Payment refunded. **isPaymentRetryScheduled**boolean Whether a retry payment is pending. Based on Program/Merchant settings, a failed payment will be retried. **isPaymentSettledToMerchant**boolean Whether the payment has been settled to the merchant. **merchantCode**string Merchant code. **merchantFee**number\ Fee charged on Merchant. **merchantName**string Merchant trading name. **merchantUniquePaymentId**string Unique payment id provided by the merchant. (Conditional). **oneOffPaymentReference**string One Off Payment Reference. **originalTransactionReference**string OriginalTransactionReference : For a Recall / Refund transaction, it is the transaction reference of original transaction. **paymentAccount**string Payment Account by which the payment is done. **paymentCard**string Payment card used. **paymentSourceDisplay**string Payment source of transaction. **preauthAmount**number\ Total payment amount including the fees. **preauthExpiryAt**string\ Preauth Expires at. **preauthReference**string Unique Payment Reference for the payment done. **preauthStatus**string Current Status of the payment. Expected Statuses 1. Pending This Payment is waiting be to processed 2. Error - This Payment has encountered an Error 3. Submitted - This Payment was successfully submitted 4. Successful - This Payment was successful 5. Successful(Recalled) - This Payment was Recalled 6. Successful(Refunded) - This Payment was Refunded 7. Successful (Refunded) (Recalled) - This Payment was Refunded and Recalled 8. Failed - This Payment has Failed 9. Cancelled - This Payment was Cancelled 10. Suppressed - This Payment was Suppressed 11. InProgress - This Payment is being processed. **processingDate**string\ Processing Date for the payment. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST. **processorReference**string Processor reference for the payment done. **recalledOn**string\ Recalled date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **recalledReason**string Reason. (Conditional). **recalledTransactionReference**string RecalledTransactionReference : If a charge transaction is recalled then this is transaction reference of recall transaction.(Conditional). **redirectUrl**string 3DSecure redirect url to complete the 3DSecure challege if required by the scheme. **refundedOn**string\ Refunded date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **refundedReason**string Reason. (Conditional). **refundedTransactionReference**string RefundedTransactionReference : If a charge transaction is refunded then this is transaction reference of refunded transaction.(Conditional). **remainingPreauthAmount**number\ Remaining preauth amount after one or more captures. **retryPaymentReference**string Retry payment reference. (Conditional). **retryScheduledOn**string\ Retry payment scheduled date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **settlementDate**string\ Settlement Date for the payment. This is a calculated date and may change until the payment been settled. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST. **transactionType**integer\ Transaction type numeric code. | Enum Value | Description | | ---------- | ----------------------------------- | | 1 | Charge | | 2 | InvoicePayment | | 3 | Refund | | 4 | Chargeback | | 5 | Recall | | 6 | FixedTermSettlement | | 7 | SponsorInvoicePayment | | 8 | MerchantSettlementAdjustmentPayment | | 9 | Preauthorization | | 10 | Credit | **transactionTypeDisplay**string Transaction Type. Possible values: 1. Charge 2. Invoice 3. Refund 4. Chargeback 5. Recall 6. Fixed Term Settlement. Preauthorization Result ```json { "abn": "string", "accountOrCardNo": "string", "additionalReference": "string", "baseAmount": 0, "cardCategory": "string", "chargeBackedOn": "2024-07-29T15:51:28.071Z", "chargeBackedReason": "string", "chargeBackedTransactionReference": "string", "customerFee": 0, "customerName": "string", "customerReference": "string", "failureCode": "string", "failureReason": "string", "fundsToMerchant": 0, "isPaymentChargeBacked": true, "isPaymentRecalled": true, "isPaymentRefunded": true, "isPaymentRetryScheduled": true, "isPaymentSettledToMerchant": true, "merchantCode": "string", "merchantFee": 0, "merchantName": "string", "merchantUniquePaymentId": "string", "oneOffPaymentReference": "string", "originalTransactionReference": "string", "paymentAccount": "string", "paymentCard": "string", "paymentSourceDisplay": "string", "preauthAmount": 0, "preauthExpiryAt": "2024-07-29T15:51:28.071Z", "preauthReference": "string", "preauthStatus": "string", "processingDate": "2024-07-29T15:51:28.071Z", "processorReference": "string", "recalledOn": "2024-07-29T15:51:28.071Z", "recalledReason": "string", "recalledTransactionReference": "string", "redirectUrl": "string", "refundedOn": "2024-07-29T15:51:28.071Z", "refundedReason": "string", "refundedTransactionReference": "string", "remainingPreauthAmount": 0, "retryPaymentReference": "string", "retryScheduledOn": "2024-07-29T15:51:28.071Z", "settlementDate": "2024-07-29T15:51:28.071Z", "transactionType": 1, "transactionTypeDisplay": "string" } ``` --- ### Preauthorization Void Result Void preauthorization response including status and transaction details. Fields marked as conditional are only returned under certain conditions. **failureCode**string Failure code if the payment failed. Please refer: for more details. (Conditional). **failureReason**string Failure reason if the payment failed. (Conditional). **preauthReference**string Unique Payment Reference for the payment done. **status**string Current Status of the void. Expected Statuses 1. Pending This Payment is waiting be to processed 2. Error - This Payment has encountered an Error 3. Submitted - This Payment was successfully submitted 4. Successful - This Payment was successful 5. Successful(Recalled) - This Payment was Recalled 6. Successful(Refunded) - This Payment was Refunded 7. Successful (Refunded) (Recalled) - This Payment was Refunded and Recalled 8. Failed - This Payment has Failed 9. Cancelled - This Payment was Cancelled 10. Suppressed - This Payment was Suppressed 11. InProgress - This Payment is being processed. Preauthorization Void Result ```json { "failureCode": "string", "failureReason": "string", "preauthReference": "string", "status": "string" } ``` --- ### Precondition Failed Response Error response returned when a precondition check fails. **errorCode**string Error code. **errorMessage**string Error message. Precondition Failed Response ```json { "errorCode": "string", "errorMessage": "string" } ``` --- ### Pricing Applicable fee for the card used. **customerFee**number\ Fee paid by the customer. **merchantFee**number\ Fee paid by the merchant. **paymentAmount**number\ Payment amount i.e. base amount excluding any fee. **processingAmount**number\ Total amount charged to the card, including any fee. Pricing ```json { "customerFee": 0, "merchantFee": 0, "paymentAmount": 0, "processingAmount": 0 } ``` --- ### Pricing Response Pricing response including applicable fees. **pricing** object Applicable pricing based on provided card and payment details. **customerFee**number\ Fee paid by the customer. **merchantFee**number\ Fee paid by the merchant. **paymentAmount**number\ Payment amount i.e. base amount excluding any fee. **processingAmount**number\ Total amount charged to the card, including any fee. Pricing Response ```json { "pricing": { "customerFee": 0, "merchantFee": 0, "paymentAmount": 0, "processingAmount": 0 } } ``` --- ### Refund Request Refund request including refund value and optional merchant unique ID. **refundAmount**number\ Refund Amount (Conditional). Amount is required when Refund Value is 'Partial' (2). **refundRequestReason**stringrequired Reason for the refund request. **Max length:** `<= 50 characters` **refundRequestUniqueId**string Refund Request Unique Id. **Max length:** `<= 50 characters` **refundValue**integer\required Refund value - Defaults to 'BaseAmount' (1) if not passed. | Enum Value | Description | | ---------- | ----------- | | 1 | Base | | 2 | Partial | | 3 | Full | Refund Request ```json { "refundAmount": 0, "refundRequestReason": "string", "refundRequestUniqueId": "string", "refundValue": 1 } ``` --- ### Refund Result Refund request response including status and refund reference. **additionalReference**string Additional Reference. **cancelReason**string Reason for the refund request cancellation. This field will returned only if the status is 'Canceled'. **merchantCode**string Merchant code. **merchantName**string Merchant trading name. **paymentReference**string Payment Reference. **refundAmount**number\ Refund Amount. **refundRequestUniqueId**string Refund Request Unique Id. **refundValue**integer\ Refund value. | Enum Value | Description | | ---------- | ----------- | | 1 | Base | | 2 | Partial | | 3 | Full | **refundValueString**string Refund value (Human readable). **rejectReason**string Reason for the refund request rejected. This field will returned only if the status is 'Rejected'. **requestReason**string Reason for the refund request. **requestStatus**integer\ Refund request status. **requestStatusString**string Refund request status (Human readable). Refund Result ```json { "additionalReference": "string", "cancelReason": "string", "merchantCode": "string", "merchantName": "string", "paymentReference": "string", "refundAmount": 0, "refundRequestUniqueId": "string", "refundValue": 1, "refundValueString": "string", "rejectReason": "string", "requestReason": "string", "requestStatus": 0, "requestStatusString": "string" } ``` --- ### Request Pay Batch Request Container for request-to-pay entries. Root element containing a collection of RequestPayEntry. **merchantUniqueRequestBatchId**string Unique batch id provided by the merchant. **Max length:** `<= 50 characters` **requestPaymentEntries** object\[]required Collection of RequestPayment entry. * Array \[ **customerReference**stringrequired Customer reference in individual payment request entry. **email**string Customer email in individual payment request entry. Use comma or semicolon to provide more than one email address for a customer. **firstName**stringrequired First name of the customer. **lastName**string Last name of the customer. **merchantUniquePaymentId**string Unique payment id provided by the merchant. Can be used when Proxy payment is performed. (Optional). **Max length:** `<= 50 characters` **mobile**string Customer mobile in individual payment request entry. **Format:** Value must match regular expression `^(04[0-9]{8}|02[0-9]{7,8})$` **paymentAmount**number\required Payment amount in individual payment request entry. **Range:** `>= 0.01` and `<= 1.7976931348623157e+308` * ] Request Pay Batch Request ```json { "merchantUniqueRequestBatchId": "string", "requestPaymentEntries": [ { "customerReference": "string", "email": "string", "firstName": "string", "lastName": "string", "merchantUniquePaymentId": "string", "mobile": "string", "paymentAmount": 0 } ] } ``` --- ### Request Pay Entry Individual entry within a request-to-pay batch including amount and recipient details. **additionalReference**string Additional reference for the payment entry. **baseAmount**number\ Base payment amount before fees. **companyName**string Company name associated with this payment entry. **customerFee**number\ Fee charged to the customer. **customerName**string Name of the customer for this payment entry. **customerReference**string Reference identifier for the customer in this payment entry. **email**string Email address for payment notifications. **entryStatus**string Current status of this payment entry. **failureCode**string Error code for the payment failure. **failureReason**string Reason the payment failed. **isPaymentRecalled**boolean Whether the payment has been recalled. **isPaymentRefunded**boolean Whether the payment has been refunded. **isPaymentRetryScheduled**boolean Whether a payment retry has been scheduled. **lastDigits**string Last digits of the payment card used. **merchantCode**string Merchant code. **merchantFee**number\ Fee charged to the merchant. **merchantName**string Merchant trading name. **merchantWithheldAmount**number\ Amount withheld from the merchant. **mobile**string Mobile number for payment notifications. **oneOffPaymentReference**string Reference for a one-off payment. **paymentAmount**number\ Amount to be paid in this entry. **paymentCard**string Card details associated with the payment. **paymentDate**string\ Scheduled date for the payment. **paymentMethod**string Method used for payment (e.g. card, direct debit). **paymentReference**string Unique reference for the payment transaction. **paymentResource**string Resource identifier for the payment. **paymentStatus**string Payment processing status. **processedAmount**number\ Total amount processed including fees. **processingDate**string\ Date the payment was processed. **processorReference**string Reference assigned by the payment processor. **recalledOn**string\ Date and time the payment was recalled. **recalledReason**string Reason the payment was recalled. **refundedOn**string\ Date and time the payment was refunded. **refundedReason**string Reason the payment was refunded. **requestReference**string Reference to the parent request-to-pay batch. **retryPaymentReference**string Reference for the retry payment transaction. **retryPaymentResource**string Resource identifier for the retry payment. **retryPaymentStatus**string Status of the retry payment. **retryScheduledOn**string\ Date and time the retry is scheduled for. **settlementDate**string\ Date the payment was settled. Request Pay Entry ```json { "additionalReference": "string", "baseAmount": 0, "companyName": "string", "customerFee": 0, "customerName": "string", "customerReference": "string", "email": "string", "entryStatus": "string", "failureCode": "string", "failureReason": "string", "isPaymentRecalled": true, "isPaymentRefunded": true, "isPaymentRetryScheduled": true, "lastDigits": "string", "merchantCode": "string", "merchantFee": 0, "merchantName": "string", "merchantWithheldAmount": 0, "mobile": "string", "oneOffPaymentReference": "string", "paymentAmount": 0, "paymentCard": "string", "paymentDate": "2024-07-29T15:51:28.071Z", "paymentMethod": "string", "paymentReference": "string", "paymentResource": "string", "paymentStatus": "string", "processedAmount": 0, "processingDate": "2024-07-29T15:51:28.071Z", "processorReference": "string", "recalledOn": "2024-07-29T15:51:28.071Z", "recalledReason": "string", "refundedOn": "2024-07-29T15:51:28.071Z", "refundedReason": "string", "requestReference": "string", "retryPaymentReference": "string", "retryPaymentResource": "string", "retryPaymentStatus": "string", "retryScheduledOn": "2024-07-29T15:51:28.071Z", "settlementDate": "2024-07-29T15:51:28.071Z" } ``` --- ### Request Pay Entry Request Individual request-to-pay entry submitted by the client. **customerReference**stringrequired Customer reference in individual payment request entry. **email**string Customer email in individual payment request entry. Use comma or semicolon to provide more than one email address for a customer. **firstName**stringrequired First name of the customer. **lastName**string Last name of the customer. **merchantUniquePaymentId**string Unique payment id provided by the merchant. Can be used when Proxy payment is performed. (Optional). **Max length:** `<= 50 characters` **mobile**string Customer mobile in individual payment request entry. **Format:** Value must match regular expression `^(04[0-9]{8}|02[0-9]{7,8})$` **paymentAmount**number\required Payment amount in individual payment request entry. **Range:** `>= 0.01` and `<= 1.7976931348623157e+308` Request Pay Entry Request ```json { "customerReference": "string", "email": "string", "firstName": "string", "lastName": "string", "merchantUniquePaymentId": "string", "mobile": "string", "paymentAmount": 0 } ``` --- ### Request Pay Response Request-to-pay response returned after submission. **merchantCode**string Merchant code. **merchantName**string Merchant trading name. **merchantUniqueRequestBatchId**string Unique request pay batch id provided by the merchant. **requestPayId**integer\ Id of RequestPay for call to Uploading. **warningMessages**string WarningMessages after processing batch. Request Pay Response ```json { "merchantCode": "string", "merchantName": "string", "merchantUniqueRequestBatchId": "string", "requestPayId": 0, "warningMessages": "string" } ``` --- ### Request Pay Summary Request-to-pay summary including status, totals, and processing details. **merchantCode**string Merchant code. **merchantName**string Merchant trading name. **merchantUniqueRequestBatchId**string Merchant-assigned unique identifier for the request-to-pay batch. **processingDate**string\ Date and time the request-to-pay was processed. **status**string Current processing status of the request-to-pay. **statusRemarks**string Additional remarks about the request-to-pay processing status. **submittedDate**string\ Date and time the request-to-pay was submitted. **totalAmount**number\ Total monetary amount of all entries in the request-to-pay. **totalEntries**integer\ Total number of entries in the request-to-pay. Request Pay Summary ```json { "merchantCode": "string", "merchantName": "string", "merchantUniqueRequestBatchId": "string", "processingDate": "2024-07-29T15:51:28.071Z", "status": "string", "statusRemarks": "string", "submittedDate": "2024-07-29T15:51:28.071Z", "totalAmount": 0, "totalEntries": 0 } ``` --- ### Settlement Payment Settlement payment details including processing date, status, settlement date, and funds to merchant. **fundsToMerchant**number\ Amount to be settled to the merchant. **merchantSettlementDate**string\ Date payment will be settled to the merchant. **processedOn**string\ Processing date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST. **status**string Current Status of the balance payment. Expected Statuses 1. Pending 2. Error 3. Submitted 4. Successful 5. Failed 6. Cancelled 7. Suppressed 8. InProgress. **transactionReference**string TransactionReference. Settlement Payment ```json { "fundsToMerchant": 0, "merchantSettlementDate": "2024-07-29T15:51:28.071Z", "processedOn": "2024-07-29T15:51:28.071Z", "status": "string", "transactionReference": "string" } ``` --- ### Sub Payment Refund or recall transaction details including date, fees, amount, reason, and status. **customerFee**number\ Fee charged on Customer. **merchantFee**number\ Fee charged on Merchant. **paymentAmount**number\ Total payment amount including the fees. **processedOn**string\ Refund/Recall date. Date Format: yyyy-MM-ddTHH:mm:ss, TimeZone: AEST (Conditional). **reason**string Reason. (Conditional). **status**string Current Status of the refund/recall. Expected Statuses 1. Pending This refund/recall is waiting be to processed 2. Error - This refund/recall has encountered an Error 3. Submitted - This refund/recall was successfully submitted 4. Successful - This refund/recall was successful 5. Failed - This refund/recall has Failed 6. Cancelled - This refund/recall was Cancelled 7. Suppressed - This refund/recall was Suppressed 8. InProgress - This refund/recall is being processed. **transactionReference**string TransactionReference : If a charge transaction is refunded/recalled then this is transaction reference of that transaction.(Conditional). Sub Payment ```json { "customerFee": 0, "merchantFee": 0, "paymentAmount": 0, "processedOn": "2024-07-29T15:51:28.071Z", "reason": "string", "status": "string", "transactionReference": "string" } ``` --- ### Validation Error Represents an error that occurs during model binding. **errorMessage**string Gets or sets the error message. **exception**object Gets or sets the exception object. Validation Error ```json { "errorMessage": "string", "exception": {} } ``` --- ### Validation Model State Encapsulates the state of model binding to a property of an action-method argument, or to the argument itself. **errors** object\[] Gets a ModelErrorCollection object that contains any errors that occurred during model binding. * Array \[ **errorMessage**string Gets or sets the error message. **exception**object Gets or sets the exception object. * ] **value** object Gets a ValueProviderResult object that encapsulates the value that was being bound during model binding. **attemptedValue**string Gets or sets the raw value that is converted to a string for display. **culture**string Gets or sets the culture. **rawValue**object Gets or set the raw value that is supplied by the value provider. Validation Model State ```json { "errors": [ { "errorMessage": "string", "exception": {} } ], "value": { "attemptedValue": "string", "culture": "string", "rawValue": {} } } ``` --- ### Validation Result Represents the result of binding a value (such as from a form post or query string) to an action-method argument property, or to the argument itself. **attemptedValue**string Gets or sets the raw value that is converted to a string for display. **culture**string Gets or sets the culture. **rawValue**object Gets or set the raw value that is supplied by the value provider. Validation Result ```json { "attemptedValue": "string", "culture": "string", "rawValue": {} } ``` --- ### Create a session [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-2a5c65e1-b229-48d5-b578-0b0ea8e561cb%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Creates a session for the payment plugin. The session created will have an expiry. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 201 Created * 400 Bad Request * 500 Internal Server Error Session created. Invalid input detail. Unable create session. Read the response content for more information. --- ### Customer APIs [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-a2be0546-51d4-46b9-9183-a988b813c5ac?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-a2be0546-51d4-46b9-9183-a988b813c5ac%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Export * [OpenAPI Spec](/openapi-v3.json) Self-service REST API for merchant customers, using a Bearer token issued by the customer through their own portal account (distinct from the Merchant API's ZenPay-issued Basic/Api-Key credentials). #### Authentication[​](#authentication "Direct link to Authentication") * HTTP: Bearer Auth | Security Scheme Type: | http | | -------------------------- | ------ | | HTTP Authorization Scheme: | bearer | ##### Contact ZenPay Integrations Team: URL: --- ### Ping method to get the server date time and version information [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-a2be0546-51d4-46b9-9183-a988b813c5ac?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-a2be0546-51d4-46b9-9183-a988b813c5ac%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Ping method to get the server date time and version information #### Responses[​](#responses "Direct link to Responses") * 200 OK Self check endpoing --- ### Get all the payments [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-a2be0546-51d4-46b9-9183-a988b813c5ac?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-a2be0546-51d4-46b9-9183-a988b813c5ac%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Get all the payments #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK OK --- ### Get a payment by unique ID [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-a2be0546-51d4-46b9-9183-a988b813c5ac?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-a2be0546-51d4-46b9-9183-a988b813c5ac%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the payment for the specified customer and unique payment ID. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK OK --- ### Get a payment by reference [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-a2be0546-51d4-46b9-9183-a988b813c5ac?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-a2be0546-51d4-46b9-9183-a988b813c5ac%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Returns the payment for the specified customer and payment reference. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK OK --- ### Create a payment [![Run in Postman](/img/run-in-postman.svg)](https://app.getpostman.com/run-collection/58558843-a2be0546-51d4-46b9-9183-a988b813c5ac?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D58558843-a2be0546-51d4-46b9-9183-a988b813c5ac%26entityType%3Dcollection%26workspaceId%3Dce7e8188-3cd4-43d6-b626-13a5a7432bb2) Creates a payment from the supplied request payload. #### Request[​](#request "Direct link to request") #### Responses[​](#responses "Direct link to Responses") * 200 OK * 201 Created * 300 Multiple Choices OK * application/json - payment-created Payment created ```json { "paymentReference": "247086", "uniquePaymentId": "v3-capture-1789805452955", "customerCode": "TB18780151", "customerName": "Ian Menethil", "customerReference": "9935442a-6930-428d-b6eb-fa969522e49a", "baseAmount": 1, "customerFee": 0, "fundsToMerchant": 0, "processedAmount": 1, "paymentAccount": "*****678", "cardType": 4, "cardTypeString": "Bank Account", "subCardType": 4, "subCardTypeString": "Bank Account", "processingDate": "2026-09-19T18:10:56", "paymentStatus": 3, "paymentStatusString": "Successful", "settlementDate": "2026-09-23", "processorReference": "PR.2420u", "isPaymentSettledToMerchant": false, "merchantName": "Menethil", "merchantCode": "1337", "isPaymentRetryScheduled": false, "processorRetryCount": 0, "isPaymentRecalled": false, "isPaymentRefunded": false, "paymentType": 1, "paymentTypeString": "Charge", "isPaymentChargeBacked": false, "paymentSource": 58, "paymentSourceString": "Cust.Api Payment", "hasPendingRefundRequest": false, "isPartialRefund": false, "refundedAmount": 0, "refundedCustomerFeeAmount": 0 } ``` * application/json - payment-id-resent Payment id resent ```json { "message": "The Payment unique id already exists." } ``` --- ### PaymentRequest **merchantCode**stringrequired **customerReference**stringrequired **paymentAmount**number\required **uniquePaymentId**stringrequired **Max length:** `<= 50 characters` **oneOffPaymentReference**string **additionalReference**string **sendPaymentConfirmation**boolean **uniqueCustomerId**string Unique Customer ID. This can be configured at the customer portal. **Max length:** `<= 20 characters` PaymentRequest ```json { "merchantCode": "string", "customerReference": "string", "paymentAmount": 0, "uniquePaymentId": "string", "oneOffPaymentReference": "string", "additionalReference": "string", "sendPaymentConfirmation": true, "uniqueCustomerId": "string" } ``` --- ### PingResponse Ping result **serverDateTime**string\ Server Date Time **version**string API version **timeZoneInfo**string DateTime Time Zone **buildVersion**string Build version PingResponse ```json { "serverDateTime": "2024-07-29T15:51:28.071Z", "version": "string", "timeZoneInfo": "string", "buildVersion": "string" } ``` --- ### Refund Guide Zenith Payments supports refund requests through the Merchant API, together with API-based status checks on those requests. This page explains how refunds work at a practical level. Use **/openapi** for the exact request and response schema details. *** #### How refunds work[​](#how-refunds-work "Direct link to How refunds work") Refunds are requested against an existing payment. Refund requests are manually approved by Zenith Payments. Because of that, creating a refund request does not mean the refund has already been completed. Your integration should treat refund creation and refund approval as separate steps. Refunds can be: * **Base Amount** — full payment amount before fees * **Partial Amount** — a merchant-specified amount up to the base amount Refund requests for the full amount including fees will generally not be approved. If that type of refund is required, contact Zenith Payments directly. *** #### Create Refund Request[​](#create-refund-request "Direct link to Create Refund Request") To initiate a refund request, make a `POST` request to: ```text /v2/payments/{paymentReference}/refundrequests ``` The refund request is tied to the `paymentReference` being refunded. ##### Refund value types[​](#refund-value-types "Direct link to Refund value types") The `refundValue` field can be set as: * `1` — Base Amount * `2` — Partial Amount If there is any possibility of multiple refunds against the same `paymentReference`, provide a `refundRequestUniqueId` so that individual refund requests can be tracked safely. See [`/openapi`](/docs/integration-options/rest-api.md) for the full request/response schema and example payloads. *** #### Check Refund Request Status[​](#check-refund-request-status "Direct link to Check Refund Request Status") To check the approval status of a refund request, make a `GET` request to: ```text /v2/payments/{paymentReference}/refundrequests ``` If there are multiple refund requests for the same payment, use the endpoint that includes the unique refund request identifier. Your integration should treat refund status retrieval as the reliable way to confirm the current state of a refund request. See [`/openapi`](/docs/integration-options/rest-api.md) for the full request/response schema and example payloads. *** #### Practical guidance[​](#practical-guidance "Direct link to Practical guidance") When implementing refunds: * keep the original `paymentReference` * use a unique refund request identifier when multiple refunds are possible * do not assume a created refund request is already approved * reconcile refund state using the API instead of UI assumptions * keep internal tracking aligned with the refund request lifecycle *** #### Related pages[​](#related-pages "Direct link to Related pages") * [REST API](/docs/integration-options/rest-api.md) * [Authentication](/docs/integration-options/rest-api/authentication.md) * [Common API Patterns](/docs/integration-options/rest-api/common-api-patterns.md) * [API Reference](/docs/integration-options/rest-api.md) *** #### Summary[​](#summary "Direct link to Summary") Refunds in the Merchant API are request-based and approval-driven. Create the refund request through the API, track it using the payment reference and refund request identifier, and confirm status separately rather than assuming immediate completion. --- ### Sessions and Hosted Checkout The Sessions API is the bridge between your backend and Hosted Checkout. Use it when your backend needs to create a secure session for the JavaScript Plugin, so the browser can launch Hosted Checkout without holding merchant credentials or other trusted secret material. It also removes the need for any other dependencies on your page. Sessions exist so your backend can authenticate with the Merchant API, create a short-lived checkout session, and return only launch-safe data to the frontend, keeping merchant credentials out of browser code entirely. *** #### High-level flow[​](#high-level-flow "Direct link to High-level flow") A typical flow looks like this: 1. customer clicks **Pay** 2. frontend calls your backend 3. backend authenticates to the Merchant API 4. backend creates a session 5. backend returns the session output to the frontend 6. frontend launches Hosted Checkout 7. payment completes through the hosted flow 8. backend confirms final state using the normal trusted path This keeps checkout launch and backend trust properly separated. *** #### What the session gives you[​](#what-the-session-gives-you "Direct link to What the session gives you") A successful session response gives your integration what it needs to initialise the browser-side checkout launch safely, without exposing raw backend credentials to the client. Use the generated API reference at `/openapi` for the exact request and response details. *** #### What Sessions are not[​](#what-sessions-are-not "Direct link to What Sessions are not") Sessions are **not** a replacement for: * callback validation * backend payment reconciliation * refund or preauth management * customer management * long-term merchant authentication A session is a launch mechanism, not a source of final payment truth. *** #### Frontend responsibilities[​](#frontend-responsibilities "Direct link to Frontend responsibilities") Your frontend should: * request session data from your backend * initialise Hosted Checkout * handle customer-facing UI * avoid holding raw Merchant API credentials *** #### Redirect and callback still matter[​](#redirect-and-callback-still-matter "Direct link to Redirect and callback still matter") Using Sessions does **not** change the core Hosted Checkout trust model. You should still treat: * **redirect** as customer-facing UX * **callback / backend validation** as authoritative confirmation Even if the session was created correctly, redirect alone should not be treated as final payment confirmation. *** #### When to use Sessions[​](#when-to-use-sessions "Direct link to When to use Sessions") Use Sessions whenever your frontend launches Hosted Checkout. If your integration is purely backend-led and never launches browser checkout, you may not need Sessions at all. *** #### Relationship to other pages[​](#relationship-to-other-pages "Direct link to Relationship to other pages") * [REST API](/docs/integration-options/rest-api.md) * [Authentication](/docs/integration-options/rest-api/authentication.md) * [Common API Patterns](/docs/integration-options/rest-api/common-api-patterns.md) * [Hosted Checkout](/docs/integration-options/hosted-checkout.md) * [API Reference](/docs/integration-options/rest-api.md) *** #### Summary[​](#summary "Direct link to Summary") Sessions let your backend create secure, short-lived launch data for Hosted Checkout, keeping credentials and trust on the backend while the frontend handles the launch. --- ## Openapi ### API Reference Zenith Payments serves two separate REST APIs. Choose the one that matches your integration. #### [Merchant APIs](/docs/integration-options/rest-api/openapi/v2/merchant-apis.md) [ZenPay-issued credentials for merchants integrating payments, preauths, refunds, and more directly.](/docs/integration-options/rest-api/openapi/v2/merchant-apis.md) [View Reference ](/docs/integration-options/rest-api/openapi/v2/merchant-apis.md) #### [Customer APIs](/docs/integration-options/rest-api/openapi/v3/customer-apis.md) [Self-service REST API for a merchant's own customers, using a Bearer token issued through their portal account.](/docs/integration-options/rest-api/openapi/v3/customer-apis.md) [View Reference ](/docs/integration-options/rest-api/openapi/v3/customer-apis.md) --- ## Release Notes ### Release Notes #### [Release 1.130](/release-notes/1.130.md) March 19, 2026 · 4 min read [![Zenith Product Team](/img/team-avatar.svg)](/release-notes/authors/product) [Zenith Product Team](/release-notes/authors/product) Product Management #### ZenPay Release 1.130[​](#zenpay-release-1130 "Direct link to ZenPay Release 1.130") This release improves the reliability of PayTo settlements and payment approvals, enhances B2Bpay's integration with accounting systems such as Xero, and makes points balances and rewards behaviour clearer for customers. **Tags:** * [Payments](/release-notes/tags/payments "Payment processing, settlements, and transaction changes") * [Integrations](/release-notes/tags/integrations "Third-party integrations, webhooks, and API updates") * [Rewards](/release-notes/tags/rewards "Points, rewards, and accelerator program changes") * [B2Bpay](/release-notes/tags/b2bpay "B2Bpay-specific features and fixes") [**Read more**](/release-notes/1.130.md) --- ## Resources ### Architecture Use this page for: * system diagrams * high-level product flows * trust boundaries * how Checkout, Payment Links, callbacks, and APIs fit together --- ### Glossary & FAQ #### General[​](#general "Direct link to General") #### Payments[​](#payments "Direct link to Payments") #### Security[​](#security "Direct link to Security") #### Technical[​](#technical "Direct link to Technical") ### Glossary This is a glossary of common terms used by Zenith Payments, or the payments industry. These terms are in the context of integrating with Zenith Payments, or other payments related terms. Search terms... Loading… --- ### Status Codes This page provides a reference for the various transaction types & payment statuses the ZenPay API. For the full API specification including request/response schemas, see the [API Reference](/docs/integration-options/rest-api.md). *** #### Transaction Types[​](#transaction-types "Direct link to Transaction Types") Each transaction processed through ZenPay is assigned a type that identifies how it was initiated and its purpose. | Code | Label | Description | | ---- | ----------------------------------- | -------------------------------------------------------------------------- | | 1 | Charge | Any payment initiated by or on behalf of a customer | | 2 | InvoicePayment | Merchant paying their ZenPay platform bill | | 3 | Refund | Funds returned to the customer for a previous transaction | | 4 | Chargeback | Customer-initiated dispute and refund through their issuing bank | | 5 | Recall | ZenPay-initiated reversal of a charge back to the customer | | 6 | FixedTermSettlement | Funds collected from a recurring installment plan | | 7 | SponsorInvoicePayment | Merchant paying for additional customer rewards points (B2B only) | | 8 | MerchantSettlementAdjustmentPayment | Manual adjustment by ZenPay Finance when a settlement date is corrected | | 9 | Preauthorisation | A hold placed on the payer's card reserving funds for a set number of days | | 10 | Credit | A standalone refund not tied to a specific prior transaction | info Transaction types appear in API responses, webhook payloads, and reporting endpoints. Use the `transactionTypes` query parameter on `GET /v2/payments` to filter by one or more types. Deprecation Notice **FixedTermSettlement (6)** is a TravelPay product that we no longer offer. If your integration filters on this type, plan to remove it. **SponsorInvoicePayment (7)** is being phased out and will be removed in a future release. If your integration filters on this type, plan to remove it. *** #### Payment Status[​](#payment-status "Direct link to Payment Status") The current processing state of a transaction. Returned in API responses, webhooks, and callbacks. Callback and Webhook use an enum code for the paymentStatus/PaymentStatus parameter and paymentStatusDisplay/PaymentStatusDisplay for the display string . The API uses paymentStatus for the display string. | Code | Webhook/Callback Display | API paymentStatus Label | Description | | ---- | -------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------- | | -1 | Pending Approval | ApprovalPending | A payment with user only permissions in merchant portal is made and is pending admin approval | | 0 | Pending | Pending | Payment is queued and waiting to be processed | | 1 | Error | Error | An error occurred during processing — the error reason will be included in the response payload | | 2 | Submitted | Submitted | Batch payment has been submitted but not yet processed | | 3 | Successful | Succesful | Payment has been processed successfully | | 3 | Successful(Recalled) | Successful(Recalled) | Payment was successful but funds have been recalled from the merchant | | 3 | Successful(Refunded) | Successful(Refunded) | Payment was successful but refunded to the customer before settlement | | 3 | Successful (Refunded) (Recalled) | Successful (Refunded) (Recalled) | Payment was successful, funds recalled from merchant and refunded to customer | | 4 | Failed | Failed | Payment has failed — a failure reason will be included in the response payload | | 5 | Cancelled | Cancelled | A pending payment that has been cancelled by ZenPay | | 6 | Suppressed | Suppressed | Payment processing has been paused, typically while a fraud investigation is underway | | 7 | InProgress | InProgress | Payment is currently being processed | | 8 | Received Externally | ProcessedExternal | Used when external payments from sources like PayID are received | | 9 | Rejected | Rejected | Portal payment made with user only permissions is rejected by admin | | 10 | Pending 3DS check | PendingPendingThreeDS | Payment is pending 3DS verification from the customer | Understanding Recalled vs Refunded * **Refunded** — Funds are returned to the customer *before* settlement to the merchant * **Recalled** — Funds are pulled *back from* the merchant after settlement has occurred These can occur together when a settled payment needs to be both recalled from the merchant and refunded to the customer. --- ### Payment Methods Zenith supports the following payment methods across all integration paths. Availability depends on your merchant account, program, and integration method. #### Supported methods[​](#supported-methods "Direct link to Supported methods") * [Cards (Visa, Mastercard, Amex, JCB, Union Pay)](/docs/resources/payment-methods/cards.md) * [Bank / PayID](/docs/resources/payment-methods/bank-npp.md) * [PayTo](/docs/resources/payment-methods/payto.md) * [Digital Wallets (Apple Pay, Google Pay, Alipay+)](/docs/resources/payment-methods/digital-wallets.md) * [Buy Now Pay Later / SlicePay](/docs/resources/payment-methods/buy-now-pay-later.md) #### Availability matrix[​](#availability-matrix "Direct link to Availability matrix") | Method | Hosted Checkout | Payment Links | REST API | | --------------- | --------------- | ------------- | ------------------------------------------ | | Cards | ✓ | ✓ | ✓ (tokenise via `/v2/cardproxies`) | | Bank / PayID | ✓ | — | — *(legacy — see note)* | | PayTo | ✓ | ✓ | status lookup only (`/v2/proxies/{token}`) | | Digital Wallets | ✓ | ✓ | — *(requires browser)* | | BNPL / SlicePay | ✓ (TravelPay) | ✓ (TravelPay) | indirect via `/v2/sessions` → HCP URL | Bank / PayID Bank one-off and PayID are supported on Hosted Checkout only and are considered legacy flows. Most real-time bank scenarios now use [PayTo](/docs/resources/payment-methods/payto.md). SlicePay on REST API There is no direct REST API endpoint for BNPL. REST API access is indirect — create a session via `/v2/sessions` to generate a hosted checkout URL that carries SlicePay. See [Sessions and Hosted Checkout](/docs/integration-options/rest-api/sessions-and-hosted-checkout.md). #### How to enable in your integration[​](#how-to-enable-in-your-integration "Direct link to How to enable in your integration") Each integration path documents its own setup for enabling methods: * **Hosted Checkout** — plugin flags, Mode 1 tokenisation, Apple Pay domain verification. See [Hosted Checkout → Payment Method Configuration](/docs/integration-options/hosted-checkout/configuring-payment-types.md#payment-method-configuration). * **Payment Links** — methods are enabled at the merchant-account level. Contact your Zenith account manager to change which methods appear on your link. * **REST API** — see [`/openapi`](/docs/integration-options/rest-api.md) for field-level contracts on `/v2/cardproxies`, `/v2/proxies`, and `/v2/sessions`. #### Related[​](#related "Direct link to Related") * [Hosted Checkout](/docs/integration-options/hosted-checkout.md) * [Payment Links](/docs/integration-options/payment-links.md) * [REST API](/docs/integration-options/rest-api.md) * [Test Cards](/docs/resources/test-cards.md) --- ### Bank and PayID Legacy flow Bank one-off payments and PayID are supported on **Hosted Checkout only**. They are not available on Payment Links or the REST API, and are considered legacy flows — most real-time bank scenarios now use [PayTo](/docs/resources/payment-methods/payto.md). #### Bank Payments[​](#bank-payments "Direct link to Bank Payments") Under Construction This page is on a coffee break. It'll be back shortly. CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION #### PayID[​](#payid "Direct link to PayID") Customers can make PayID payments from within their bank account application or online banking portal by using a unique PayID identifier. Customers then enter the PayID (which is an email address) and a PayID description to make a payment to the merchant. Unlike traditional bank transfers, there is instant verification of payment success, or notification of insufficient funds. Zenith Payments supports three different types of PayID levels. More details about each of the different PayID types can be found below. **Summary of PayID Types** | Comparison | **Program PayID** | **Customer PayID** | **Merchant PayID** | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | **PayID Type Example** | Every merchant in the program has the same PayID email address. [pay@travelpay.com.au](https://mailto:pay@travelpay.com.au) | Every customer in the program has a unique PayID email address. [john_12345678@travelpay.com.au](https://mailto:john_12345678@travelpay.com.au) | Every merchant in the program has a different PayID email address: @travelpay.com.au | | **Suitable For** | Most merchants wanting to quickly implement PayID. | Ongoing payments when customers may be inclined to enter the wrong reference when they pay. | One-off transactions / invoice payments | | **Customer profile and CML required? (Customer-Merchant Link)** | Yes | Yes | No | | **PayID Description the customer needs to enter** | PayID description the customer needs to enter | The customer can enter whatever reference they like. | Reference provided by the merchant on the invoice, etc. | | **Customer Reference used in reports (reconciliation, etc.)** | The customer reference stored in the customer's profile for that merchant. | The customer reference stored in the customer's profile for that merchant. | "Description/Message" field the customer enters in their bank app/site when paying | | **Additional Reference used in reports** | "Description/Message" field the customer enters in their bank app/site when paying | "Description/Message" field the customer enters in their bank app/site when paying | "Reference" field the customer enters in their bank app/site when paying | | **Advantages** | Easy to implement. | The merchant always receives the stored customer reference even if the customer enters the wrong reference when paying. | Easy to use and easy to implement; merchant adds their PayID to their invoice template. | ##### Tokenisation[​](#tokenization "Direct link to Tokenisation") You can tokenise a PayID and then use that token to create a customer via Program Level PayID and Customer Level PayID. ##### Merchant Level[​](#merchant-level "Direct link to Merchant Level") Merchant Level PayID provides the merchant with a unique PayID email address that they can put on their invoices or send to customers so that their customers can use to make a payment to that merchant. * One-off transactions * Ad hoc Invoice payments * Does not require a Zenith Payments customer profile (CML) to work. * The PayID reference is generated upon creation and is provided by the merchant * Customer enters in the correct reference as specified by the merchant to assist the merchant with reconciliation ###### How does a Merchant create a PayID Email Address?[​](#how-does-a-merchant-create-a-payid-email-address "Direct link to How does a Merchant create a PayID Email Address?") For this type of integration, PayID is created by the Zenith Support staff for the requested merchant/s. ###### How does a customer make a PayID payment?[​](#how-does-a-customer-make-a-payid-payment "Direct link to How does a customer make a PayID payment?") Coming soon... ##### Customer Level[​](#customer-level "Direct link to Customer Level") Coming soon... ##### Program Level[​](#program-level "Direct link to Program Level") Coming soon... --- ### Buy Now Pay Later #### SlicePay[​](#slicepay "Direct link to SlicePay") TravelPay merchants only SlicePay is only available to TravelPay merchants. Please speak to your BDM about enabling this payment method. SlicePay is the Buy Now Pay Later option offered through Zenith for TravelPay programs. ##### Availability[​](#availability "Direct link to Availability") | Integration | Supported? | Notes | | --------------- | ---------- | ------------------------------------------------------------------------------------ | | Hosted Checkout | ✓ | Appears alongside other enabled methods in the plugin | | Payment Links | ✓ | Appears on the hosted payment link when enabled on the merchant account | | REST API | ✓ indirect | Via `/v2/sessions` — the session returns a hosted checkout URL that carries SlicePay | SlicePay on REST API There is no direct REST API endpoint for SlicePay. Backend integrations create a session through `/v2/sessions`, which returns a hosted checkout URL that the customer opens to complete the SlicePay flow. See [Sessions and Hosted Checkout](/docs/integration-options/rest-api/sessions-and-hosted-checkout.md). Under Construction This page is on a coffee break. It'll be back shortly. CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION #### Related[​](#related "Direct link to Related") * [Payment Methods](/docs/resources/payment-methods.md) * [Hosted Checkout → BNPL / SlicePay](/docs/integration-options/hosted-checkout/configuring-payment-types.md#bnpl-slicepay) * [Sessions and Hosted Checkout](/docs/integration-options/rest-api/sessions-and-hosted-checkout.md) --- ### Cards Card payments are the most common payment method on Zenith. Cards are supported across every integration path. #### Supported schemes[​](#supported-schemes "Direct link to Supported schemes") * Visa * Mastercard * American Express * JCB * Union Pay Scheme availability may depend on your merchant account configuration and program. #### Tokenisation[​](#tokenisation "Direct link to Tokenisation") Tokenisation lets you store a card for later reuse without holding card data yourself. Zenith returns a token that you can charge later through your normal payment flow. Card tokenisation is available on two surfaces: * **Hosted Checkout (Mode 1)** — launch the JavaScript Plugin in Mode 1 and the customer is prompted to capture card details; a token is returned via redirect and callback. See [Hosted Checkout → Cards](/docs/integration-options/hosted-checkout/configuring-payment-types.md#cards). * **REST API** — the `/v2/cardproxies` endpoint provides a direct card-tokenisation surface for backend-led integrations. See [`/openapi`](/docs/integration-options/rest-api.md) for the exact contract. note `/v2/cardproxies` only tokenises cards. It does not tokenise bank accounts. For real-time bank account tokenisation, use [PayTo](/docs/resources/payment-methods/payto.md). #### 3D Secure (3DS)[​](#3d-secure-3ds "Direct link to 3D Secure (3DS)") 3DS is handled as part of the hosted payment flow when the issuer or scheme requires authentication. Merchants do not implement 3DS challenge handling directly — the hosted flow presents the challenge and returns the outcome through the normal result path. #### Card category reporting[​](#card-category-reporting "Direct link to Card category reporting") The callback payload returns a `cardCategory` field (for example `International Cards` or `Domestic`) so you can report on card geography and adjust fees or reconciliation accordingly. See [Callbacks and Validation — Payload Reference](/docs/integration-options/hosted-checkout/callbacks.md#callback-payload-reference) for the full payload shape. #### Availability[​](#availability "Direct link to Availability") | Integration | Supported? | Notes | | --------------- | ---------- | ------------------------------------------------------------- | | Hosted Checkout | ✓ | One-off, tokenise (Mode 1), preauth (Mode 3), custom (Mode 2) | | Payment Links | ✓ | Enabled at merchant-account level | | REST API | ✓ | Card tokenisation via `/v2/cardproxies` | #### Related[​](#related "Direct link to Related") * [Payment Methods](/docs/resources/payment-methods.md) * [Hosted Checkout → Cards](/docs/integration-options/hosted-checkout/configuring-payment-types.md#cards) * [Hosted Checkout](/docs/integration-options/hosted-checkout.md) * [Test Cards](/docs/resources/test-cards.md) * [`/openapi`](/docs/integration-options/rest-api.md) — REST API reference --- ### Digital Wallets Zenith supports Apple Pay, Google Pay, and Alipay+ as digital wallet payment methods. Wallets appear on your integration whenever they are enabled on your merchant account. Availability Digital wallets are available on **Hosted Checkout** and **Payment Links**. They are **not** available as a direct REST API payment method — wallets require a browser surface to render the wallet button and collect the wallet credential. #### Apple Pay[​](#apple-pay "Direct link to Apple Pay") Apple Pay is offered through Zenith wherever the merchant has Apple Pay enabled on their account. ##### Device availability[​](#device-availability "Direct link to Device availability") Due to Apple restrictions, Apple Pay can only be processed on Apple devices. On non-apple devices, a QR code will be displayed to scan on an Apple device. ##### Integration setup[​](#integration-setup "Direct link to Integration setup") Enabling Apple Pay on a Hosted Checkout integration requires a domain verification step (placing a file in `.well-known`). That step is only needed when you host the ZenPay JavaScript Plugin yourself. Payment Links are fully Zenith-hosted, so merchants using Payment Links do not need to do any Apple Pay domain verification. See [Hosted Checkout → Apple Pay](/docs/integration-options/hosted-checkout/configuring-payment-types.md#apple-pay) for the plugin-specific domain verification steps. #### Google Pay[​](#google-pay "Direct link to Google Pay") Under Construction This page is on a coffee break. It'll be back shortly. CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION #### Alipay+[​](#alipay "Direct link to Alipay+") Under Construction This page is on a coffee break. It'll be back shortly. CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION CAUTION #### Related[​](#related "Direct link to Related") * [Payment Methods](/docs/resources/payment-methods.md) * [Hosted Checkout → Digital Wallets](/docs/integration-options/hosted-checkout/configuring-payment-types.md#google-pay-alipay) * [Payment Links](/docs/integration-options/payment-links.md) --- ### PayTo Zenith supports PayTo, the real-time bank account payment solution built on the NPP (New Payment Platform). PayTo enables a secure and fast way to process real‑time payments from Australian bank accounts with instant approval and without the current 3-day settlement delay. #### Tokenised Integration Process Flow[​](#tokenised-integration-process-flow "Direct link to Tokenised Integration Process Flow") ##### Flow Diagram[​](#flow-diagram "Direct link to Flow Diagram") ##### Customer adds PayTo account to Wallet[​](#customer-adds-payto-account-to-wallet "Direct link to Customer adds PayTo account to Wallet") * Zenith will enable PayTo so that it appears in the existing Payment Plugin, in Tokenisation mode. * PayTo tab appears alongside existing methods, e.g. Card and Bank Account. * You/merchants can decide to replace the current Bank Account option with PayTo or have both. * Customers paying by Bank Account can continue to do so, even if it is decided to only offer PayTo when new accounts are added. * Customer enters their Account Name, BSB, and Account Number and are instructed to approve the mandate in their banking APP. * You receive a token / Payment Account Proxy, in the same way as for card or bank account. * As the customer needs to approve the mandate in their bank APP, you should record / display the PayTo account in the customer’s wallet as “Pending Mandate Approval.” ![PayTo step 1](/assets/images/payto-1-b1088adaad6656c25527217c57ea61d0.png) ![PayTo step 2](/assets/images/payto-2-a29e6d10bd35dcb7b41ff10311b43c09.png) ##### Customer PayTo Mandate Approval[​](#customer-payto-mandate-approval "Direct link to Customer PayTo Mandate Approval") * The customer approves the PayTo mandate in their banking APP / site. * This is a one-time only step, which confirms the customer’s authorisation and account ownership. * The customer receives an email/SMS/app prompt from their bank to approve the PayTo agreement * Each bank has different approaches – here are some examples: ![PayTo step 3](/assets/images/payto-3-5ff122f276ad3ff672f2668b423b4341.jpg) ![PayTo step 4](/assets/images/payto-4-ca04ea6d2a7b5783e0521a40f8564f41.png) ![PayTo step 5](/assets/images/payto-5-e536387db00f93d3c8893895700433df.png) ##### PayTo Token Status – WebHook[​](#payto-token-status--webhook "Direct link to PayTo Token Status – WebHook") * When the PayTo mandate is approved, declined or subsequently cancelled, Zenith will post a WebHook call which will also contain the current status. **Active PayTo token – WebHook Example:** ```json { "Version": 1, "Event": "Edit", "PayloadType": "PayToProxy", "Payload": { "AccountType": "PayTo", "AccountName": "AppToken", "AccountNumber": "417529874", "BSB": "012204", "CardType": "PayTo", "PayToStatus": "Active", "Token": "b95045c7-bcb0-4f9b-8029-c1d3566c9883", "StatusDescription": null } } ``` ##### PayTo Token Status – API[​](#payto-token-status--api "Direct link to PayTo Token Status – API") * You can also call an API to find out the status of a PayTo mandate. * Endpoint: `GET /v2/proxies/\{token\}` — returns the current PayTo proxy status. **Active PayTo token – API Example Response:** ```json { "accountType": "PayTo", "accountName": "AppToken", "accountNumber": "417529874", "bsb": "012204", "payToStatus": "Active", "cardType": "PayTo", "uId": "6b26376a-ca87-4734-ab6b-10cfc8f1b3ca" } ``` ##### Payment Processing[​](#payment-processing "Direct link to Payment Processing") * There is no change required to payment processing – just send the PayTo token / proxy when you are processing a transaction. * PayTo transactions will be instantly successful or failed. * PayTo transactions processed before 8am SYD on business days will be settled to the merchant on the same day. #### PayTo – Existing Integration Uplift[​](#payto--existing-integration-uplift "Direct link to PayTo – Existing Integration Uplift") As you already utilise the Payment Plugin for tokenisation or one-off payments, you only need to do the following: ##### Pass PayTo parameter when loading Zenith Plugin[​](#pass-payto-parameter-when-loading-zenith-plugin "Direct link to Pass PayTo parameter when loading Zenith Plugin") * For tokenisation and/or one off payments, pass: allowPayToOneOffPayment: true * Upon entering their details in the plugin, the customer will be advised to approve their PayTo mandate in their bank app. * If tokenising, when the customer selects PayTo and enters banking details, a token / proxy is created – in the same way as a card or bank account. ##### Handle PayTo Tokens[​](#handle-payto-tokens "Direct link to Handle PayTo Tokens") * Flag newly created PayTo tokens with a ‘Pending PayTo Mandate Approval’ status (or similar) in your system wallet / list of bank account pages. * This ensures your customer knows that approval is required, in addition to the notification in the query and that their bank will send to them. * We suggest you include wording in your system wallet (whilst PayTo account is Pending Mandate Approval) to remind the customer to activate their PayTo mandate in their bank App. ##### Support WebHook/API calls[​](#support-webhookapi-calls "Direct link to Support WebHook/API calls") * Receive and action the Zenith Customer WebHook which is triggered when the customer approves / declines / cancels the PayTo mandate in their bank app. * You can also check the status of a PayTo token via API. Please see appendix below. * When the customer approves their PayTo mandate, update the status of the PayTo bank account in your system wallet to ‘Active’ or similar. * A customer can cancel their PayTo mandate at any time in their banking app. This will trigger a WebHook call to enable you to manage it. * Alternatively, you can call our API to get status updates. ##### Payments[​](#payments "Direct link to Payments") * No change – just pass the PayTo token in the same way you would pass a bank / card token. #### Overview (Tokenisation)[​](#overview-tokenisation "Direct link to Overview (Tokenisation)") * Launch plugin in Mode 1 (tokenise) * Customer enters bank details, selects Tokenise * Plugin authorises (Mode 1); token created as Pending * Redirect and callback deliver token details * Customer approves mandate in bank app * Webhook or API calls indicate token is Active * Your system can now charge the token Participants: Customer → Browser/Plugin → Zenith Hosted Page → Bank App → Merchant Server ##### Mandate lifecycle and statuses[​](#mandate-lifecycle-and-statuses "Direct link to Mandate lifecycle and statuses") * Pending: Token created. Awaiting customer approval in banking app * Active: Approved. safe to charge * Paused: Account holder has paused the mandate, and the token cannot be charged until it becomes active again * Cancelled: Account holder has cancelled the mandate, and the account will need to be re-tokenised * Declined: Bank or customer has declined the mandate **How you know the current proxy status** * Webhooks: receive PayTo proxy events on changes * API lookup: `GET /v2/proxies/\{token\}` returns payToStatus #### One-Off Integration[​](#one-off-integration "Direct link to One-Off Integration") Pay-To acts like any other one-off payment method with the exception of a prompt for the customer to approve the payment via their banking portal or SMS notification. Once approval is given, the payment is made, and the mandate is cancelled. More detail about initial stages can be found in the above section on tokenising. ##### Flow Diagram[​](#flow-diagram-1 "Direct link to Flow Diagram") --- ### Test Cards note **Please note - these cards are for Sandbox & require the below** * Card expiry date must be a future date * Card name and CVV accept any value in Sandbox info 3DS is not available for tokenisation in Sandbox. To simulate a failure, set the total amount (including fees) to exactly $65.00 using a failure card — this returns error 2003 (Test decline) #### Success/Failure Cards[​](#successfailure-cards "Direct link to Success/Failure Cards") **General Errors** | **Card Type** | **Test Card Number** | **Transaction Status** | | ---------------- | -------------------- | ---------------------- | | American Express | 3782 8224631 0005 | Success | | Visa | 4111 1111 1111 1111 | Success | | Visa | 4242 4242 4242 4242 | Failure | | Mastercard | 5555 5555 5555 4444 | Success | | Mastercard | 5105 1051 0510 5100 | Failure | | Union Pay | 6250 9460 0000 0016 | Success | | Union Pay | 6250 9470 0000 0014 | Failure | | JCB | 3530 1113 3330 0000 | Success | #### 3DS Simulation[​](#3ds-simulation "Direct link to 3DS Simulation") | Card Type | Test Card Number | Result | | ---------- | ------------------- | ---------------------------------- | | Mastercard | 5000 0010 0000 0007 | Challenge | | Visa | 4000 0010 0000 0000 | Frictionless - Fully Authenticated | | Visa | 4111 1111 1111 1111 | Frictionless - Fully Authenticated | | Visa | 4000 0020 0000 0008 | Frictionless - Fully Authenticated | | Visa | 4000 0010 0000 0216 | Frictionless - Attempted | | Visa | 4000 0020 0000 0016 | Frictionless - Attempted | | Visa | 4000 0010 0000 0109 | Challenge | | Visa | 4000 0020 0000 0024 | Challenge | | Visa | 4000 0010 0000 0307 | Not Authenticated | | Visa | 4000 0020 0000 0032 | Not Authenticated | | Visa | 4000 0010 0000 0208 | Rejected | | Visa | 4000 0020 0000 0040 | Rejected | | Visa | 4000 0030 0000 0006 | Error: Not Enrolled | | Visa | 4000 0030 0000 0014 | Error: Network Timeout | | Visa | 4000 0030 0000 0022 | Error: Network Error | | Visa | 4000 0030 0000 0030 | Error: Invalid card | | Visa | 4000 0040 0000 0004 | Error: Access Denied | | Visa | 4000 0040 0000 0012 | Error: Transient System Error | | Visa | 4000 0040 0000 0020 | Error: Invalid Format | | Visa | 4000 0040 0000 0038 | Error: Network Timeout | | Visa | 4000 0040 0000 0046 | Error: Network Error | | Visa | 4000 0040 0000 0053 | Error: Configuration missing | | Visa | 4000 0040 0000 0061 | Error: Configuration incomplete | #### PayTo Test BSBs[​](#payto-test-bsbs "Direct link to PayTo Test BSBs") | **BSB** | **Result** | | ------- | ------------------------------------ | | 111-111 | Debtor account type not supported | | 222-222 | Debtor decline | | 333-333 | Expired | | 444-444 | Debtor alias not found | | 555-555 | Creditor alias not found | | 666-666 | Alias resolution service unavailable | | 777-777 | Agreement service unavailable | * If payment amount >= 6000, this will simulate `Insufficient Funds` * If payment amount >= 5000, this will simulate `Requires Investigation` --- ### Developer Tools Interactive utilities to help you integrate, test, and debug Zenith Payments. #### [🔍URL Parser](/tools/parser) [Dissect, analyse, and modify URLs or JSON payloads.](/tools/parser) #### [🔑Fingerprint Generator](/tools/generator) [Create valid security hashes for development and testing.](/tools/generator) #### [✅Fingerprint Validator](/tools/validator) [Advanced diagnostic tool for verifying payment security hashes.](/tools/validator) #### [📦BatchPay Generator](/tools/batchpay-generator) [Embedded external tool for creating standardized batch payment files for download.](/tools/batchpay-generator) #### [🔗URL Generator](/tools/url-generator) [Embedded external tool for generating payment URLs for one-off or recurring payments.](/tools/url-generator) #### [🎨HCP CSS Builder](/tools/hcp-css-builder) [Build, preview and export a CSS theme for the hosted checkout against the real page.](/tools/hcp-css-builder) #### [📏HCP CSS Validator](/tools/hcp-css-validator) [Check a checkout stylesheet against the hosted-checkout CSS policy and see what to fix.](/tools/hcp-css-validator) #### [🧪Webpod Sandbox](/webpod) [Browser-based sandbox for running the HCP hosted-checkout integration samples end-to-end.](/webpod) --- ### Webhooks Webhooks are merchant-wide, event-based notifications configured once at the merchant account level by Zenith. The merchant provides an HTTPS endpoint URL, and Zenith registers it against the merchant account. Once registered, Zenith will POST JSON payloads whenever: * A transaction status changes (e.g. Pending → Successful) across any payment method or channel. * PayTo mandate status changes * isSettledToMerchant status changes Webhooks are dispatched on a scheduler/timer that evaluates states and posts updates. All payment methods and channels trigger the same webhook mechanism. Per-transaction callbacks If you are using the [Payment Plugin](/docs/integration-options/hosted-checkout.md) and need immediate, per-transaction notifications, see [Callbacks and Validation](/docs/integration-options/hosted-checkout/callbacks.md#callbacks-overview). Callbacks are plugin-only and apply to a single transaction. #### Callbacks vs Webhooks[​](#callbacks-vs-webhooks "Direct link to Callbacks vs Webhooks") **Requirements** * **HTTPS POST endpoint** – Must be reachable from Zenith's servers. * **Stable URL** – The endpoint is configured once by Zenith; changes require contacting Zenith. #### Webhook Payload Fields[​](#webhook-payload-fields "Direct link to Webhook Payload Fields") | Field | Type | Notes | | ---------------------------- | ------- | ---------------------------------------------------------------------- | | `Version` | number | Payload version number. | | `Event` | string | Event type (e.g. `NEW`, `EDIT`). | | `PayloadType` | string | Type of payload delivered (e.g. `Payment, Customer`). | | `PaymentReference` | string | Unique payment reference assigned by Zenith. | | `CustomerName` | string | null | | `CustomerReference` | string | Reference provided by the merchant. | | `PaymentStatus` | number | Numeric status code. | | `PaymentStatusDisplay` | string | Human-readable payment status. | | `BaseAmount` | number | Base amount before fees. | | `FundsToMerchant` | number | Net amount payable to the merchant. | | `CustomerFee` | number | Fee charged to the customer. | | `MerchantFee` | number | Fee charged to the merchant. | | `PaymentAmount` | number | Total amount of the transaction. | | `AccountOrCardNo` | string | Masked account or card number. | | `PaymentMethod` | number | Numeric code for the payment method. | | `PaymentMethodDisplay` | string | Human-readable payment method. | | `PaymentCardType` | number | Numeric code for the card type. | | `PaymentCardTypeDisplay` | string | Human-readable card type. | | `SubCardType` | string | null | | `SubtCardTypeDisplay` | string | null (Field name is misspelled, this is not an error in documentation) | | `ProcessingDateTime` | string | UTC ISO-8601 datetime (`yyyy-MM-ddTHH:mm:ss`). | | `SettlementDate` | string | UTC ISO-8601 date (`yyyy-MM-dd`). | | `ProcessorReference` | string | Reference from the processor/gateway. | | `IsPaymentSettledToMerchant` | boolean | Indicates if the payment has been settled. | | `MerchantUniquePaymentId` | string | null | | `MerchantCode` | string | Merchant identifier. | | `AdditionalReference` | string | null | | `PaymentSource` | number | Numeric source identifier. | | `PaymentSourceDispaly` | string | Field name is misspelled, this is not an error in documentation | | `IsPaymentRecalled` | boolean | Indicates if the payment has been recalled. | | `IsPaymentRefunded` | boolean | Indicates if the payment has been refunded. | #### Webhook Payload Example[​](#webhook-payload-example "Direct link to Webhook Payload Example") ```json { "Version": 1, "Event": "New", "PayloadType": "Payment", "Payload": { "PaymentReference": "210768", "CustomerName": null, "CustomerReference": "1", "PaymentStatus": 3, "PaymentStatusDisplay": "Successful", "BaseAmount": 155.08, "FundsToMerchant": 155.08, "CustomerFee": 4, "MerchantFee": 0, "PaymentAmount": 159.08, "AccountOrCardNo": "411111XXXXXX1111", "PaymentMethod": 0, "PaymentMethodDisplay": "Credit / Debit Card", "PaymentCardType": 1, "PaymentCardTypeDisplay": "Visa - International Cards", "SubCardType": null, "SubtCardTypeDisplay": null, "ProcessingDateTime": "2025-08-27T22:08:14", "SettlementDate": "2025-08-28", "ProcessorReference": "2a41cff0e84ee15f8b42", "IsPaymentSettledToMerchant": false, "MerchantUniquePaymentId": null, "MerchantCode": "1337", "AdditionalReference": null, "PaymentSource": 39, "PaymentSourceDispaly": "Api Tokenised Payment", "IsPaymentRecalled": false, "IsPaymentRefunded": false } } ``` #### Webhook Payload Updates[​](#webhook-payload-updates "Direct link to Webhook Payload Updates") When a webhook for a particular payment referenced is first created and sent, the `Event` will be **New**. Any subsquent webhooks reflecting status updates to that payment will have the `Event`: **Edit**. --- ## Security ### Security #### Best Practices[​](#best-practices "Direct link to Best Practices") For our recommended security best practices, see our [Best Practices guide](/docs/integration-guides/best-practices.md) #### PCI DSS[​](#pci-dss "Direct link to PCI DSS") Every organisation that handles card payments must comply with the Payment Card Industry Data Security Standard (PCI DSS). Annual compliance is mandated by the payment card schemes and banks. ##### What is PCI DSS?[​](#what-is-pci-dss "Direct link to What is PCI DSS?") PCI DSS is a global standard, helping to protect cardholder data and tackle the growing threat of security breaches. It sets the operational and technical requirements for organisations handling card payments, and for software developers and manufacturers of payment applications and devices. Zenith Payment's entire infrastructure is fully compliant with PCI DSS - we are certified at Level 1, which is the highest level of compliance. We are independently audited annually for compliance by qualified security assessors. Please find our PCI DSS certificate here: [PCI Certificate](https://www.zenithpayments.com.au/Zenith-Payments-PCI-Certificate.pdf) ##### What this means for you?[​](#what-this-means-for-you "Direct link to What this means for you?") Whilst Zenith Payments is a PCI DSS compliant organisation, if your organisation does accept card payments then it must also be fully compliant, though not to the same level. Non-compliance with PCI DSS could make you responsible for any losses through fraud, and you may also face considerable fines from the card schemes and banks. There are four levels of compliance, dependent on how many transactions are processed by your organisation in a year. Find out how your organisation can reach compliance at the [PCI Security Standards Council Website](https://www.pcisecuritystandards.org/pci_security/maintaining_payment_security) More specific information can be found at the [PCI Security Standards Documentation](https://www.pcisecuritystandards.org/document_library/) site, searching for "SAQ". For most merchants, the "SAQ Instructions and Guidelines" and "SAQ-A" are the appropriate documents. Please refer to this site for the most up to date standards. #### 3DS[​](#3ds "Direct link to 3DS") 3D Secure (3DS), often recognised by brand names like Visa Secure or Mastercard Identity Check, is a security protocol designed to provide an additional layer of authentication for online credit and debit card transactions. The "three domains" refer to the Acquirer (the merchant's bank), the Issuer (the customer's bank), and the Interoperability Domain (the infrastructure supporting the protocol). When a transaction is processed via 3DS, the customer is typically prompted by their bank to verify their identity using a one-time passcode, a mobile app notification, or biometric authentication. This process is handled upstream of Zenith Payments and no action is needed from developers when using our payment plugin. #### Data Protection and Tokenisation[​](#data-protection-and-tokenization "Direct link to Data Protection and Tokenisation") Tokenisation substitutes card details with unique token values that are usable only in permitted payment contexts. This lowers direct handling of raw card data and supports safer recurring or repeat-payment experiences. ##### Why Tokenisation Matters[​](#why-tokenization-matters "Direct link to Why Tokenisation Matters") * Improves security by limiting exposure of sensitive card details. * Supports payment-data protection practices used across modern payment systems. * Enables convenient returning-customer payment flows without re-entering full card details. #### Shared Responsibility[​](#shared-responsibility "Direct link to Shared Responsibility") ZenPay provides hosted payment controls and platform-level protections, but merchants still play an important role in maintaining a secure payment operation. Merchants should: * protect internal access to payment-related systems and reports * review payment outcomes and investigate unusual activity * train teams to recognise phishing and social-engineering risks * use secure internal processes when handling customer and payment data ---