This page is a ZenPay-styled copy of the Zenith Payments developer documentation. View the original docs

Sessions API

A session is a secure, time-limited token used to initialize the hosted payment plugin. Sessions configure payment methods, amounts, customization, and callback URLs.

Create a session#

POST/v2/sessions

View this endpoint in the original docs

Creates a session for the payment plugin. The session created will have an expiry.

Authentication: Api-Key + BasicAuth

Request body

Session details required to create a session.

Content types: application/json, application/x-www-form-urlencoded · required

Schema: SessionRequest

Field	Type	Description
`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 (PluginPaymentMethods)	Allowed Payment methods.
`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 (PluginCustomization)	Optional. Fields to customize the plugin fields.
`departureDate`	string <date-time>	Conditional. DepartureDate is required for Slice Pay. Provide date in UTC ISO 8601 format as departureDate. format: yyyy-MM-dd.
`displayMode` required	integer <int32>	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. Allowed values: `0` Default, `1` RedirectUrl
`endpointUrl` required	string	Endpoint url of the plugin. Just provide the base url. For example: https://pay.travelpay.com.au.
`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` required	boolean	Is JS Plugin. Default is true. Set to false if you want to use without iframe.
`merchantCode` required	string	Merchant code. Make sure the merchant code is related to the API credentials.
`merchantUniquePaymentId` required	string	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` required	integer <int32>	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. Allowed values: `0` DefaultPayment, `1` Tokenise, `2` CustomPayment, `3` Preauth
`overrideFeePayer`	integer <int32>	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. Allowed values: `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 <double>	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` required	string	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` required	string <date-time>	Required. Timestamp is required from v4. Provide current datetime in UTC ISO 8601 format as timestamp. format: yyyy-MM-ddTHH:mm:ss.
`userMode` required	integer <int32>	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. Allowed values: `0` Customer, `1` Merchant
`version` required	integer <int32>	Required. Plugin version. Always use the latest. Allowed values: `1` v1, `2` v2, `3` v3, `4` v4, `5` v5

Example: Payment session created

Baseline session response and request. It proves session creation, not a completed hosted payment.

JSON

{
  "additionalReference": "sweep-row-2",
  "allowSaveCardInformation": true,
  "allowedPaymentMethods": {
    "aliPayPlus": true,
    "applePay": true,
    "bankAccount": true,
    "googlePay": true,
    "latitudePay": false,
    "payId": true,
    "payTo": true,
    "slicePay": false,
    "unionPay": true,
    "weChat": true
  },
  "businessNumber": "51824753556",
  "callbackUrl": "https://httpbin.org/post",
  "companyName": "Test Company Pty Ltd",
  "contactNumber": "0400000000",
  "customerEmail": "test@zenpay.com.au",
  "customerName": "Test Customer",
  "customerReference": "cr-sweep-0912",
  "customization": {
    "customerNameLabel": "Customer Name",
    "customerReferenceLabel": "Customer Reference",
    "hideHeader": false,
    "hideMerchantLogo": false,
    "paymentAmountLabel": "Amount",
    "title": "Sweep Test Payment"
  },
  "departureDate": "2026-12-22T14:36:40",
  "displayMode": 0,
  "endpointUrl": "https://pay.sandbox.b2bpay.com.au",
  "hideTermsAndConditions": false,
  "isJsPlugin": true,
  "merchantCode": "1337",
  "merchantUniquePaymentId": "cli-session-5670038468670",
  "mode": 0,
  "overrideFeePayer": 0,
  "paymentAmount": 1,
  "redirectOnError": false,
  "redirectUrl": "https://httpbin.org/get",
  "sendConfirmationEmailToCustomer": false,
  "sendConfirmationEmailToMerchant": false,
  "showFailedPaymentFeeOnTokenising": true,
  "showFeeOnTokenising": true,
  "sku1": "SKU-TEST-001",
  "sku2": "SKU-TEST-002",
  "timestamp": "2026-09-23T14:36:40",
  "userMode": 0,
  "version": 5
}

Example: Preauth session created

Promote this distinct session purpose. Drop the unproven fee claim from its name; session creation proves no fee allocation.

JSON

{
  "additionalReference": "sweep-row-2",
  "allowSaveCardInformation": true,
  "allowedPaymentMethods": {
    "aliPayPlus": true,
    "applePay": true,
    "bankAccount": true,
    "googlePay": true,
    "latitudePay": false,
    "payId": true,
    "payTo": true,
    "slicePay": false,
    "unionPay": true,
    "weChat": true
  },
  "businessNumber": "51824753556",
  "callbackUrl": "https://httpbin.org/post",
  "companyName": "Test Company Pty Ltd",
  "contactNumber": "0400000000",
  "customerEmail": "test@zenpay.com.au",
  "customerName": "Test Customer",
  "customerReference": "cr-sweep-0912",
  "customization": {
    "customerNameLabel": "Customer Name",
    "customerReferenceLabel": "Customer Reference",
    "hideHeader": false,
    "hideMerchantLogo": false,
    "paymentAmountLabel": "Amount",
    "title": "Sweep Test Payment"
  },
  "departureDate": "2026-12-22T14:36:40",
  "displayMode": 0,
  "endpointUrl": "https://pay.sandbox.b2bpay.com.au",
  "hideTermsAndConditions": false,
  "isJsPlugin": true,
  "merchantCode": "1337",
  "merchantUniquePaymentId": "cli-session-8617774627869",
  "mode": 3,
  "overrideFeePayer": 2,
  "paymentAmount": 1,
  "redirectOnError": false,
  "redirectUrl": "https://httpbin.org/get",
  "sendConfirmationEmailToCustomer": false,
  "sendConfirmationEmailToMerchant": false,
  "showFailedPaymentFeeOnTokenising": true,
  "showFeeOnTokenising": true,
  "sku1": "SKU-TEST-001",
  "sku2": "SKU-TEST-002",
  "timestamp": "2026-09-23T14:36:40",
  "userMode": 0,
  "version": 5
}

Example: Tokenisation session created

Distinct session purpose. Current capture is broad; replace it with the focused capture identified below, not an edited payload.

JSON

{
  "additionalReference": "sweep-row-2",
  "allowSaveCardInformation": true,
  "allowedPaymentMethods": {
    "aliPayPlus": true,
    "applePay": true,
    "bankAccount": true,
    "googlePay": true,
    "latitudePay": false,
    "payId": true,
    "payTo": true,
    "slicePay": false,
    "unionPay": true,
    "weChat": true
  },
  "businessNumber": "51824753556",
  "callbackUrl": "https://httpbin.org/post",
  "companyName": "Test Company Pty Ltd",
  "contactNumber": "0400000000",
  "customerEmail": "test@zenpay.com.au",
  "customerName": "Test Customer",
  "customerReference": "cr-sweep-0912",
  "customization": {
    "customerNameLabel": "Customer Name",
    "customerReferenceLabel": "Customer Reference",
    "hideHeader": false,
    "hideMerchantLogo": false,
    "paymentAmountLabel": "Amount",
    "title": "Sweep Test Payment"
  },
  "departureDate": "2026-12-22T14:36:40",
  "displayMode": 0,
  "endpointUrl": "https://pay.sandbox.b2bpay.com.au",
  "hideTermsAndConditions": false,
  "isJsPlugin": true,
  "merchantCode": "1337",
  "merchantUniquePaymentId": "cli-session-3049030055990",
  "mode": 1,
  "overrideFeePayer": 0,
  "paymentAmount": 1,
  "redirectOnError": false,
  "redirectUrl": "https://httpbin.org/get",
  "sendConfirmationEmailToCustomer": false,
  "sendConfirmationEmailToMerchant": false,
  "showFailedPaymentFeeOnTokenising": true,
  "showFeeOnTokenising": true,
  "sku1": "SKU-TEST-001",
  "sku2": "SKU-TEST-002",
  "timestamp": "2026-09-23T14:36:40",
  "userMode": 0,
  "version": 5
}

Responses

201 Session created.

application/json · object (SessionResponse)

Example: Payment session created

Baseline session response and request. It proves session creation, not a completed hosted payment.

JSON

{
  "endpointUrl": "https://pay.sandbox.b2bpay.com.au/online/v5/1337/yCo-3w4eOku7yWHb9XxQUA/auth",
  "expiresAt": "2026-09-23T15:06:40.9081026+00:00",
  "secureToken": "yCo-3w4eOku7yWHb9XxQUA"
}

Example: Preauth session created

Promote this distinct session purpose. Drop the unproven fee claim from its name; session creation proves no fee allocation.

JSON

{
  "endpointUrl": "https://pay.sandbox.b2bpay.com.au/online/v5/1337/Q2OCFRkxik6vdu1J-Etyig/auth",
  "expiresAt": "2026-09-23T15:06:41.2675143+00:00",
  "secureToken": "Q2OCFRkxik6vdu1J-Etyig"
}

Example: Tokenisation session created

Distinct session purpose. Current capture is broad; replace it with the focused capture identified below, not an edited payload.

JSON

{
  "endpointUrl": "https://pay.sandbox.b2bpay.com.au/online/v5/1337/jAsRrvN4U0ykNt46ol4Q9w/auth",
  "expiresAt": "2026-09-23T15:06:41.0487372+00:00",
  "secureToken": "jAsRrvN4U0ykNt46ol4Q9w"
}

400 Invalid input detail.

application/json · object

500 Unable create session. Read the response content for more information.

Example request (cURL, sandbox host)

cURL

curl -X POST 'https://api.sandbox.zenpay.com.au/v2/sessions' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Content-Type: application/json' \
  -d '{
  "additionalReference": "sweep-row-2",
  "allowSaveCardInformation": true,
  "allowedPaymentMethods": {
    "aliPayPlus": true,
    "applePay": true,
    "bankAccount": true,
    "googlePay": true,
    "latitudePay": false,
    "payId": true,
    "payTo": true,
    "slicePay": false,
    "unionPay": true,
    "weChat": true
  },
  "businessNumber": "51824753556",
  "callbackUrl": "https://httpbin.org/post",
  "companyName": "Test Company Pty Ltd",
  "contactNumber": "0400000000",
  "customerEmail": "test@zenpay.com.au",
  "customerName": "Test Customer",
  "customerReference": "cr-sweep-0912",
  "customization": {
    "customerNameLabel": "Customer Name",
    "customerReferenceLabel": "Customer Reference",
    "hideHeader": false,
    "hideMerchantLogo": false,
    "paymentAmountLabel": "Amount",
    "title": "Sweep Test Payment"
  },
  "departureDate": "2026-12-22T14:36:40",
  "displayMode": 0,
  "endpointUrl": "https://pay.sandbox.b2bpay.com.au",
  "hideTermsAndConditions": false,
  "isJsPlugin": true,
  "merchantCode": "1337",
  "merchantUniquePaymentId": "cli-session-5670038468670",
  "mode": 0,
  "overrideFeePayer": 0,
  "paymentAmount": 1,
  "redirectOnError": false,
  "redirectUrl": "https://httpbin.org/get",
  "sendConfirmationEmailToCustomer": false,
  "sendConfirmationEmailToMerchant": false,
  "showFailedPaymentFeeOnTokenising": true,
  "showFeeOnTokenising": true,
  "sku1": "SKU-TEST-001",
  "sku2": "SKU-TEST-002",
  "timestamp": "2026-09-23T14:36:40",
  "userMode": 0,
  "version": 5
}'

Need help with your integration?Talk to the Zenith Integrations Team.

Email integrations Talk to us