Test Your Key
Quick Demo
Result
Use the Quick Demo or Test Your Key to see the result here.
Code Sample

Include the following in your code

Stylesheet: https://cdn.<<PROGRAM DOMAIN>>.com.au/css/zenpay.payment.css
Javascript: https://cdn.<<PROGRAM DOMAIN>>.com.au/js/zenpay.payment.js

The implementation depends on jQuery version 3.7.1 and requires jQuery to be included in your code.

Execute the following jQuery code on the click of your ”Pay Now” button.

var payment = $.zpPayment({
    url: 'https://<<PROGRAM SUB-DOMAIN>>.<<PROGRAM DOMAIN>>/online/v5',
    merchantCode: '<<MERCHANT-CODE>>',
    MerchantUniquePaymentId: '<<UNIQUE-PAYMENT-ID>>',
    apiKey: '<<API-KEY>>',
    fingerprint: '<<FINGERPRINT>>',
    redirectUrl: '<<Your Redirect URL>>',
    mode: 0,
    displayMode: 0,
    customerName: 'Customer Name',
    customerReference: 'Reference 1',
    CustomerEmail: 'sample@test.com',
    paymentAmount: 100.00,
    timeStamp: '<<TIMESTAMP>>'
});
var result = payment.init();
PROGRAM DOMAIN, PROGRAM SUB-DOMAIN, and API-KEY will be provided by Zenith Payments. (Note that these will be different for each environment i.e. Live and UAT )
For FINGERPRINT refer to the parameter details below.

Input Parameters
Field NameData TypeConditionalRemarks
urlstringRequiredPlugin access url. We strongly recommend v5 integration.
merchantCodestringRequiredAs provided by Zenith.
apiKeystringRequiredAs provided by Zenith
fingerprintstringRequiredThe Fingerprint is a SHA3-512 (v5), SHA512 (v4) or SHA1 hash (v3) of the fields in the following order with a pipe (|) as a separator.

Credentials provided by Zenith Payments are case sensitive.

apiKey|userName|password|mode|paymentAmount|merchantUniquePaymentId|timestamp

apiKey: refer apiKey parameter
userName: provided by Zenith Payments
password: provided by Zenith Payments
mode: refer mode parameter
paymentAmount: provide payment amount in cents without symbol. e.g. for $150.53 pass 15053. Pass 0 when mode is 2.
merchantUniquePaymentId: refer merchantUniquePaymentId parameter
timestamp: : provide current datetime in UTC ISO 8601 format as timestamp. format: yyyy-MM-ddTHH:mm:ss

SHA3-512 (applicable for v5) - To generate fingerprint for this page you can use online SHA3-512 generator>.
SHA512 (applicable for v4) - To generate fingerprint for this page you can use online SHA512 generator.
SHA1 (applicable for v3) - To generate fingerprint for this page you can use online SHA1 generator.
For methods of generating a SHA1 hash (applicable for v3) in your language refer this web site.
redirectUrlstringRequiredThe page will redirect to this URL with the result in the query string. Refer the return parameters section below.
redirectOnErrorstringOptionalIf this is set to true, all validation and processing errors are returned part of the redirect url. Default is 'false'.
modeintOptional

Must be one of the following three values
0 - Make Payment
1 - Tokenise
2 - Custom Payment
3 - Preauthorization

Defaults to 0 if not provided.

displayModeintOptional

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.

customerNamestringConditionalRequired if mode is set to 0 or 2.
CustomerNameLabelstringOptionalCustom label to override default customer name display text
customerReferencestringConditionalRequired if mode is set to 0 or 2.
CustomerReferenceLabelstringOptionalCustom label to override default customer reference display text
paymentAmountnumberConditionalRequired if mode is set to 0 or 2.
Returns applicable fee if provided with mode 1.
PaymentAmountLabelstringOptionalCustom label to override default payment amount display text
allowBankAcOneOffPaymentboolean
(true/false)
ConditionalRequired if mode is set to 0 or 2.
Show bank account option only if the option is enable for the merchant. Default is false.
allowPayToOneOffPaymentboolean
(true/false)
ConditionalRequired if mode is set to 0 or 2.
Show PayTo bank account option only if the option is enable for the merchant. Default is false.
allowPayIdOneOffPaymentboolean
(true/false)
ConditionalRequired if mode is set to 0 or 2.
Show PayID option only if the option is enable for the merchant. Default is false.
allowApplePayOneOffPaymentboolean
(true/false)
ConditionalConditional if mode is set to 0.
Show Apple Pay option only if the option is enable for the merchant. Default is false.
allowGooglePayOneOffPaymentboolean
(true/false)
ConditionalConditional if mode is set to 0.
Show Google Pay option only if the option is enable for the merchant. Default is false.
allowLatitudePayOneOffPaymentboolean
(true/false)
ConditionalConditional if mode is set to 0.
Show Latitude Pay option only if the option is enable for the merchant. Default is false.
allowSlicePayOneOffPaymentboolean
(true/false)
ConditionalConditional if mode is set to 0.
Show Slice Pay option only if the option is enable for the merchant. Default is false.
allowUnionPayOneOffPaymentboolean
(true/false)
ConditionalConditional if mode is set to 0.
Show UnionPay option only if the option is enable for the merchant. Default is true.
allowAliPayPlusOneOffPaymentboolean
(true/false)
ConditionalConditional if mode is set to 0.
Show AliPay+ option only if the option is enable for the merchant. Default is true.
showFeeOnTokenisingboolean
(true/false)
ConditionalRequired if mode is set to 1.
Show the applicable fees for the token at the end of the process. Default is false.
showFailedPaymentFeeOnTokenisingboolean
(true/false)
ConditionalOptional if mode is set to 1.
Show the applicable failed payment fees for the token at the end of the process. Default is false.
merchantUniquePaymentIdstringRequiredPayment id provided by the merchant. Must be unique and can not be reused if a transaction is processed using this id.
timestampstringConditionaltimestamp is required for v4 and optional for v3. Provide current datetime in UTC ISO 8601 format as timestamp. format: yyyy-MM-ddTHH:mm:ss
cardProxystringOptionalUse this parameter to make a payment using a card proxy which is generated using mode '1'.
callbackUrlstringOptionalThe URL will be called with HTTP POST method to submit the result. Refer the return parameters section below.
hideTermsAndConditionsboolean
(true/false)
OptionalThis will hide the Terms and Conditions.
Defaults to 'false' if not provided.
sendConfirmationEmailToMerchantboolean
(true/false)
OptionalThis will send confirmation email to merchant.
Defaults to 'false' if not provided.
additionalReferencestringOptionalAdditional reference to identify customer. This will be passed on to the merchant reconciliation file (PDF & CSV)
contactNumberstringOptionalContact number
customerEmailstringConditionalEmail address to which invoice will be emailed if the merchant is configured.
It is mandatory in V4.
ABNstringOptionalAustralian Business Number. Used for reward programs if the Program is enabled to provide reward points.
companyNamestringOptionalCustomer company name.
titlestringOptionalPlugin Title.
Defaults to 'Tokenise Account' for Mode 1 (Tokenise), otherwise 'Process Payment'.
hideHeaderboolean
(true/false)
OptionalThis will hide the program header including program logo.
Defaults to 'true' if not provided.
hideMerchantLogoboolean
(true/false)
OptionalThis will hide the merchant logo if any.
Defaults to 'false' if not provided.
overrideFeePayerintOptionalMust 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.
departureDatestringOptionaldepartureDate is required for Slice Pay. Provide date in UTC ISO 8601 format as departureDate. format: yyyy-MM-dd
userModeintOptionalMust 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.
minHeightintOptionalFor Mode 0 and 2 height defaults to 725px, for mode 1 height defaults to 450px if not provided.
onPluginClosefunctionOptionalJavascript callback function to execute when plug-in is closed.
sendConfirmationEmailToCustomerboolean
(true/false)
OptionalThis will send confirmation email to customer.
Defaults to 'false' if not provided.
allowSaveCardUserOptionboolean
(true/false)
OptionalThis 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.
sku1stringOptionalStock 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.
sku2stringOptionalStock 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.
Return Parameters

The following parameters are returned in mode 0 and 2. Same payload is also delivered in JSON format if callback URL is provided.

ParameterValue
result

Possible values (case insensitive):

success => Processing successful
failed => Processing failed
error => All validation errors and generic errors. This means, the plugin did not processed the request

CustomerNameSame as input parameter.
CustomerReferenceSame as input parameter.
MerchantUniquePaymentIdSame as input parameter.
AccountOrCardNoAccount or card number used to process payment.
PaymentReferencePayment reference. (applicable for Payment)
PreauthReferencePreauthorization reference. (applicable for Preauthorization)
ProcessorReferenceProcessor reference.
PaymentStatusPossiible values

0 => (Pending)
1 => (Error)
3 => (Successful)
4 => (Failed)
5 => (Cancelled)
6 => (Suppressed)
7 => (InProgress)
PaymentStatusStringPossiible values

Pending
Error
Successful
Failed
Cancelled
Suppressed
InProgress
PreauthStatusPossiible values

0 => (Pending)
1 => (Error)
3 => (Successful)
4 => (Failed)
5 => (Cancelled)
6 => (Suppressed)
7 => (InProgress)
PreauthStatusStringPossiible values

Pending
Error
Successful
Failed
Cancelled
Suppressed
InProgress
TransactionSourcePossiible values

36 => (Public_OnlineOneOffPayment)
TransactionSourceStringPossiible values

Public_OnlineOneOffPayment
ProcessingDateThe date and time when the payment is processed.
format:

yyyy-MM-ddTHH:mm:ss
SettlementDateThe date when the payment is settled to the merchant.
format:

yyyy-MM-dd
IsPaymentSettledToMerchantFlag to indicate whetehr the funds are settled to the merchant or not.
BaseAmountSame as payment amount.
CustomerFeeFee charged to the the customer to process the payment.
ProcessedAmountBase amount + Customer fee. (applicable for Payment)
PreauthAmountBase amount + Customer fee. (applicable for Preauthorization)
FundsToMerchantBase amount - Merchant fee, if applicable.
MerchantCodeMerchant code.
FailureCodePopulated only when payment is not successful.
FailureReasonPopulated only when payment is not successful.
TokenReturned only if payment is processed using cardProxy input parameter. The value will be same as cardProxy.
PayIdReturned only if payment is processed using PayID.
PayIdNameReturned only if payment is processed using PayID. Display name for the PayID


The following parameters are returned in mode 1. Same payload is also delivered in JSON format if callback URL is provided.

ParameterValue
TokenThe proxy that can be saved and then use to process payment using API or payment plugin.
CardTypeType of card i.e. Visa, MasterCards, Ammercican Express Or Bank Account.
CardHolderNameCard holder name provided by the user. Returned only if user selects credit / debit card.
CardNumberObfuscated card number provided by the user. Returned only if user selects credit / debit card.
CardExpiryCard expiry date. Returned only if user selects credit / debit card.
format:

MM/CCYY
AccountNameAccount name provided by the user. Returned only if user selects bank account.
AccountNumberObfuscated account number provided by the user. Returned only if user selects bank account.
PayIdReturned only if payment is processed using PayID.
PayIdNameReturned only if payment is processed using PayID. Display name for the PayID
IsRestrictedCardFlag to indicate whetehr the card is restricted or not.
PaymentAmountSame as input parameter.
CustomerFeeCustomer fee applicable to process a payment of amount specified in PaymentAmount input parameter.
MerchantFeeMerchant fee applicable to process a payment of amount specified in PaymentAmount input parameter.
ProcessingAmountThe total amount that will be processed i.e. PaymentAmount + CustomerFee.


Note

The payload submitted to the callbackURL has an additional parameter called ValidationCode. You can use this validation code to authenticate the callback.

The ValidationCode is a SHA3-512 (v5), SHA512 (v4) or SHA1 (v3) hash of the fields in the following order with a pipe (|) as a separator.

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


In case of mode 0 and 2, the reference is PaymentReference output parameter and in case of mode 1, the reference is Token output parameter.
Refer the Fingerprint input parameter above for more information.

Error Codes

The following table illustrates the meaning of error codes returned.

Error CodeDescription
E01Make sure fingerprint and apikey are passed.
E02-*MerchantUniquePaymentId cannot be empty.
E03-*The fingerprint should be unique everytime.
This can be achieved by using new MerchantUniquePaymentId and current Timestamp everytime the plugin is opened.
E04Invalid Credentials. Applicable for V1 and V2(V1 and V2 are deprecated).
E05Make sure fingerprint and apikey are passed.
E06Account is not active. Contact administrator.
E07Provided endpoint is not supported.
E08Invalid Credentials. Make sure fingerprint is correctly generated, refer to fingerprint generation logic.
E09Security violation. Close and open the plugin with fresh fingerprint.
E10Security violation. Close and open the plugin with fresh fingerprint.
E11Timestamp cannot be empty. Make sure to pass same timestamp as in generated fingerprint.
E13MerchantCode provided does not match with the provided credentials.
E14Security violation. Close and open the plugin with fresh fingerprint.
E15MerchantCode cannot be empty(V4 onwards).
E16Version can not be empty.
E17CustomerEmail can not be empty(V4 onwards).
E18DepartureDate is required for Slice Pay.
E19Invalid Timestamp. Timestamp needs to be in UTC ISO 8601 format.