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

The Pre-Auth Reference can be created via our Payment Plugin using mode 3 (see Plugin Documentation 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

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.

Example Callback response:

{
	"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

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:

{
	"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

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:

{
	"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

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:

{
	"preauthReference": "101998",
	"status": "Successful"
}