Developers
LoginTalk to us

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

Preauths API

A preauthorization places a hold on a customer's card for a specified amount. Preauthorizations can later be captured (converted to a payment) or voided (released).

List preauthorizations#

GET/v2/preauths

View this endpoint in the original docs

Returns preauthorizations that match the supplied filter criteria.

Authentication: Api-Key + BasicAuth

Parameters

NameInTypeDescription
customerReferencequerystring

Filter by the merchant's unique reference for the customer.

fromProcessedDatequerystring <date-time>

Return preauthorizations processed on or after this date and time. Format: ISO 8601 date-time.

toProcessedDatequerystring <date-time>

Return preauthorizations processed on or before this date and time. Format: ISO 8601 date-time.

offsetqueryinteger <int32>

The zero-based index of the first record to return. Default: 0.

Default: 0
limitqueryinteger <int32>

The maximum number of records to return.

Default: 20

Responses

200 Found preauths.

application/json · array of object (PreauthResponse)

Example: Preauths for one customer

A populated list containing different preauth outcomes; do not hard-code an old item count in the summary.

JSON
[
  {
    "abn": "51824753556",
    "accountOrCardNo": "555555XXXXXX4444",
    "additionalReference": "ex-preauth",
    "baseAmount": 1,
    "cardCategory": "International Cards",
    "customerFee": 0,
    "customerName": "Test Customer",
    "customerReference": "cust-pre-8330623881192",
    "fundsToMerchant": 0,
    "isPaymentChargeBacked": false,
    "isPaymentRecalled": false,
    "isPaymentRefunded": false,
    "isPaymentRetryScheduled": false,
    "isPaymentSettledToMerchant": false,
    "merchantCode": "1337",
    "merchantFee": 0.05,
    "merchantName": "Menethil",
    "merchantUniquePaymentId": "pre-cap-1139152540592",
    "paymentAccount": "Card",
    "paymentCard": "MasterCard",
    "paymentSourceDisplay": "Api Tokenised Preauth",
    "preauthAmount": 1,
    "preauthExpiryAt": "2026-09-29T00:36:59.393",
    "preauthReference": "247432",
    "preauthStatus": "Successful",
    "processingDate": "2026-09-24T00:36:59.393",
    "processorReference": "fd93b022d15c098549ea",
    "remainingPreauthAmount": 0,
    "transactionType": 9,
    "transactionTypeDisplay": "Preauthorization"
  }
]

Example request (cURL, sandbox host)

cURL
curl -X GET 'https://api.sandbox.zenpay.com.au/v2/preauths' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Accept: application/json'

Create a preauthorization#

POST/v2/preauths

View this endpoint in the original docs

Creates a preauthorization from the supplied request payload.

Authentication: Api-Key + BasicAuth

Request body

Preauthorization details required to create a preauthorization.

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

Schema: PreauthRequest

FieldTypeDescription
abnstring

Customer Australian Business Number.

additionalReferencestring

Additional reference. This field is returned in reconciliation reports.

cardobject (PaymentCard)

PAN detail.

cardProxystring

Card Proxy (Conditional). Use only if you want to pay using card proxy.

companyNamestring

Customer company name.

contactNumberstring

Customer contact number.

customerEmailstring

The customer email to which an invoice is sent to.

customerNamestring

Customer name.

customerReference requiredstring

Customer reference. Required only when payment account proxy or card proxy is not provided.

merchantUniquePaymentIdstring

Unique payment id provided by the merchant.

Max length: 50
oneOffPaymentReferencestring

One Off Payment reference. This field is returned in reconciliation reports.

overrideFeePayerinteger <int32>

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).

Allowed values: 0 Default, 1 Merchant, 2 Customer
paymentAccountProxyobject (AccountProxy)

Card or bank account proxy. Proxy is generated using the Payments Plugin for bank account and card or /cardProxies API for card.

preauthAmount requirednumber <double>

Preauth amount.

threeDSecureDataobject (ThreeDSecureData)

Optional. 3DSecure details.

Example: Preauth with a card proxy

Tokenised-card input.

JSON
{
  "cardProxy": "feb4e012caec4329976e437100a566b6",
  "customerReference": "cust-pre-1959173251176",
  "merchantUniquePaymentId": "pre-proxy-7501045558834",
  "preauthAmount": 1
}

Example: Preauth with a payment account proxy

General proxy input.

JSON
{
  "customerReference": "cust-pre-8148794145090",
  "merchantUniquePaymentId": "pre-pap-2128434321377",
  "paymentAccountProxy": {
    "label": "preauth pap",
    "proxy": "f655a7cc495a4f29a976ccdf87724821"
  },
  "preauthAmount": 1
}

Example: Preauth with card details

Prefer the simpler direct-card request over the optional-field-heavy create.

JSON
{
  "card": {
    "cardHolder": "Test Cardholder",
    "cardNumber": "5555555555554444",
    "cvv": "123",
    "expiryMonth": "10",
    "expiryYear": "2030"
  },
  "customerReference": "cust-pre-3089411743683",
  "merchantUniquePaymentId": "pre-void-1020706351846",
  "preauthAmount": 1
}

Example: Preauth with the stored customer method

Customer-reference-only funding input; do not label it as proof the customer paid the fee.

JSON
{
  "customerReference": "cust-pre-4244871898321",
  "merchantUniquePaymentId": "pre-fee-customer-8386960408417",
  "overrideFeePayer": 2,
  "preauthAmount": 1
}

Responses

201 Preauth is created.

application/json · object (PreauthResponse)

Example: Declined preauth

Essential distinction: HTTP success can contain a failed preauth outcome.

JSON
{
  "accountOrCardNo": "424242XXXXXX4242",
  "baseAmount": 1,
  "customerFee": 0,
  "customerReference": "cust-pre-2621060456847",
  "failureCode": "2003",
  "failureReason": "The transaction was declined (Test decline)",
  "fundsToMerchant": 0,
  "isPaymentChargeBacked": false,
  "isPaymentRecalled": false,
  "isPaymentRefunded": false,
  "isPaymentRetryScheduled": false,
  "isPaymentSettledToMerchant": false,
  "merchantCode": "1337",
  "merchantFee": 0.05,
  "merchantName": "Menethil",
  "merchantUniquePaymentId": "pre-decline-9232492623152",
  "paymentAccount": "Card",
  "paymentCard": "Visa",
  "paymentSourceDisplay": "Api Tokenised Preauth",
  "preauthAmount": 1,
  "preauthExpiryAt": "2026-09-29T00:37:17.5346242",
  "preauthReference": "247443",
  "preauthStatus": "Failed",
  "processingDate": "2026-09-24T00:37:17.5346242",
  "processorReference": "e51246d28d887dd86e98",
  "remainingPreauthAmount": 1,
  "transactionType": 9,
  "transactionTypeDisplay": "Preauthorization"
}

Example: Preauth with a card proxy

Tokenised-card input.

JSON
{
  "accountOrCardNo": "555555XXXXXX4444",
  "baseAmount": 1,
  "customerFee": 0,
  "customerReference": "cust-pre-1959173251176",
  "fundsToMerchant": 0,
  "isPaymentChargeBacked": false,
  "isPaymentRecalled": false,
  "isPaymentRefunded": false,
  "isPaymentRetryScheduled": false,
  "isPaymentSettledToMerchant": false,
  "merchantCode": "1337",
  "merchantFee": 0.05,
  "merchantName": "Menethil",
  "merchantUniquePaymentId": "pre-proxy-7501045558834",
  "paymentAccount": "Card",
  "paymentCard": "MasterCard",
  "paymentSourceDisplay": "Api Tokenised Preauth",
  "preauthAmount": 1,
  "preauthExpiryAt": "2026-09-29T00:37:12.815603",
  "preauthReference": "247441",
  "preauthStatus": "Successful",
  "processingDate": "2026-09-24T00:37:12.815603",
  "processorReference": "5c46f7a9344a3b37c12c",
  "remainingPreauthAmount": 1,
  "transactionType": 9,
  "transactionTypeDisplay": "Preauthorization"
}

Example: Preauth with a payment account proxy

General proxy input.

JSON
{
  "accountOrCardNo": "555555XXXXXX4444",
  "baseAmount": 1,
  "customerFee": 0,
  "customerReference": "cust-pre-8148794145090",
  "fundsToMerchant": 0,
  "isPaymentChargeBacked": false,
  "isPaymentRecalled": false,
  "isPaymentRefunded": false,
  "isPaymentRetryScheduled": false,
  "isPaymentSettledToMerchant": false,
  "merchantCode": "1337",
  "merchantFee": 0.05,
  "merchantName": "Menethil",
  "merchantUniquePaymentId": "pre-pap-2128434321377",
  "paymentAccount": "Card",
  "paymentCard": "MasterCard",
  "paymentSourceDisplay": "Api Tokenised Preauth",
  "preauthAmount": 1,
  "preauthExpiryAt": "2026-09-29T00:36:54.6585957",
  "preauthReference": "247429",
  "preauthStatus": "Successful",
  "processingDate": "2026-09-24T00:36:54.6585957",
  "processorReference": "38e04bec3280e3d7d668",
  "remainingPreauthAmount": 1,
  "transactionType": 9,
  "transactionTypeDisplay": "Preauthorization"
}

Example: Preauth with card details

Prefer the simpler direct-card request over the optional-field-heavy create.

JSON
{
  "accountOrCardNo": "555555XXXXXX4444",
  "baseAmount": 1,
  "customerFee": 0,
  "customerReference": "cust-pre-3089411743683",
  "fundsToMerchant": 0,
  "isPaymentChargeBacked": false,
  "isPaymentRecalled": false,
  "isPaymentRefunded": false,
  "isPaymentRetryScheduled": false,
  "isPaymentSettledToMerchant": false,
  "merchantCode": "1337",
  "merchantFee": 0.05,
  "merchantName": "Menethil",
  "merchantUniquePaymentId": "pre-void-1020706351846",
  "paymentAccount": "Card",
  "paymentCard": "MasterCard",
  "paymentSourceDisplay": "Api Tokenised Preauth",
  "preauthAmount": 1,
  "preauthExpiryAt": "2026-09-29T00:37:25.9255714",
  "preauthReference": "247445",
  "preauthStatus": "Successful",
  "processingDate": "2026-09-24T00:37:25.9255714",
  "processorReference": "4455ff2855e49fed48ba",
  "remainingPreauthAmount": 1,
  "transactionType": 9,
  "transactionTypeDisplay": "Preauthorization"
}

Example: Preauth with the stored customer method

Customer-reference-only funding input; do not label it as proof the customer paid the fee.

JSON
{
  "accountOrCardNo": "555555XXXXXX4444",
  "baseAmount": 1,
  "customerFee": 0,
  "customerReference": "cust-pre-4244871898321",
  "fundsToMerchant": 0,
  "isPaymentChargeBacked": false,
  "isPaymentRecalled": false,
  "isPaymentRefunded": false,
  "isPaymentRetryScheduled": false,
  "isPaymentSettledToMerchant": false,
  "merchantCode": "1337",
  "merchantFee": 0.05,
  "merchantName": "Menethil",
  "merchantUniquePaymentId": "pre-fee-customer-8386960408417",
  "paymentAccount": "Card",
  "paymentCard": "MasterCard",
  "paymentSourceDisplay": "Api Tokenised Preauth",
  "preauthAmount": 1,
  "preauthExpiryAt": "2026-09-29T00:37:20.6441068",
  "preauthReference": "247444",
  "preauthStatus": "Successful",
  "processingDate": "2026-09-24T00:37:20.6441068",
  "processorReference": "514b16db3417d8735c0d",
  "remainingPreauthAmount": 1,
  "transactionType": 9,
  "transactionTypeDisplay": "Preauthorization"
}

300 Duplicate merchant unique id.

application/json · object

400 Invalid input detail.

application/json · object

403 Invalid permission.

application/json · object

500 Something went wrong. Preauth may or may not be created.

application/json · object

Example request (cURL, sandbox host)

cURL
curl -X POST 'https://api.sandbox.zenpay.com.au/v2/preauths' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Content-Type: application/json' \
  -d '{
  "cardProxy": "feb4e012caec4329976e437100a566b6",
  "customerReference": "cust-pre-1959173251176",
  "merchantUniquePaymentId": "pre-proxy-7501045558834",
  "preauthAmount": 1
}'

Get a preauthorization by reference#

GET/v2/preauths/{preauthReference}

View this endpoint in the original docs

Returns preauthorization details for the specified preauthorization reference.

Authentication: Api-Key + BasicAuth

Parameters

NameInTypeDescription
preauthReference requiredpathstring

The unique reference for the preauthorization.

Responses

200 Found the preauth.

application/json · object (PreauthResponse)

Example: Preauth

Baseline lookup of a hold.

JSON
{
  "abn": "51824753556",
  "accountOrCardNo": "555555XXXXXX4444",
  "additionalReference": "ex-preauth",
  "baseAmount": 1,
  "cardCategory": "International Cards",
  "customerFee": 0,
  "customerName": "Test Customer",
  "customerReference": "cust-pre-8330623881192",
  "fundsToMerchant": 0,
  "isPaymentChargeBacked": false,
  "isPaymentRecalled": false,
  "isPaymentRefunded": false,
  "isPaymentRetryScheduled": false,
  "isPaymentSettledToMerchant": false,
  "merchantCode": "1337",
  "merchantFee": 0.05,
  "merchantName": "Menethil",
  "merchantUniquePaymentId": "pre-cap-1139152540592",
  "paymentAccount": "Card",
  "paymentCard": "MasterCard",
  "preauthAmount": 1,
  "preauthExpiryAt": "2026-09-29T00:36:59.393",
  "preauthReference": "247432",
  "preauthStatus": "Successful",
  "processingDate": "2026-09-24T00:36:59.393",
  "processorReference": "fd93b022d15c098549ea",
  "remainingPreauthAmount": 1,
  "transactionType": 9,
  "transactionTypeDisplay": "Preauthorization"
}

404 Unable to find the preauth by the reference provided.

application/json · object

Example request (cURL, sandbox host)

cURL
curl -X GET 'https://api.sandbox.zenpay.com.au/v2/preauths/{preauthReference}' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Accept: application/json'

Capture a preauthorization#

POST/v2/preauths/{preauthReference}/captures

View this endpoint in the original docs

Captures the specified preauthorization.

Authentication: Api-Key + BasicAuth

Parameters

NameInTypeDescription
preauthReference requiredpathstring

The unique reference for the preauthorization.

Request body

Capture details required to capture the specified preauthorization.

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

Schema: CaptureCardRequest

FieldTypeDescription
additionalReferencestring

Additional reference. This field is returned in reconciliation reports.

merchantUniquePaymentIdstring

Unique payment id provided by the merchant.

Max length: 50
oneOffPaymentReferencestring

One Off Payment reference. This field is returned in reconciliation reports.

paymentAmount requirednumber <double>

Amount to capture.

sendPaymentConfirmationboolean

Flag to send the customer invoice.

Example: Capture exceeds the remaining hold

Keep the amount-bearing request alongside the refusal; the error scenario teaches a constraint.

JSON
{
  "merchantUniquePaymentId": "capture-over-4505624413024",
  "paymentAmount": 100,
  "sendPaymentConfirmation": false
}

Example: Preauth captured

Shows conversion of a hold into a separate payment.

JSON
{
  "additionalReference": "ex-capture",
  "merchantUniquePaymentId": "capture-2931752970907",
  "oneOffPaymentReference": "cap-oneoff-8077238399302",
  "paymentAmount": 1,
  "sendPaymentConfirmation": false
}

Responses

201 Preauth has been captured.

application/json · object (CaptureCardResponse)

Example: Preauth captured

Shows conversion of a hold into a separate payment.

JSON
{
  "abn": "51824753556",
  "accountOrCardNo": "555555XXXXXX4444",
  "baseAmount": 1,
  "customerFee": 0,
  "customerName": "Test Customer",
  "customerReference": "cust-pre-8330623881192",
  "fundsToMerchant": 1,
  "isPaymentChargeBacked": false,
  "isPaymentRecalled": false,
  "isPaymentRefunded": false,
  "isPaymentRetryScheduled": false,
  "isPaymentSettledToMerchant": false,
  "merchantCode": "1337",
  "merchantFee": 0.05,
  "merchantName": "Menethil",
  "merchantUniquePaymentId": "capture-2931752970907",
  "paymentAccount": "Card",
  "paymentAmount": 1,
  "paymentCard": "MasterCard",
  "paymentReference": "247434",
  "paymentSourceDisplay": "Api Tokenised Payment",
  "paymentStatus": "Successful",
  "preauthExpiryAt": "2026-09-29T00:36:59.393",
  "processingDate": "2026-09-24T00:37:00.9245589",
  "processorReference": "31802b20b72daee39421",
  "remainingPreauthAmount": 0,
  "settlementDate": "2026-09-24T00:00:00",
  "transactionType": 1,
  "transactionTypeDisplay": "Charge"
}

300 The merchant unique id already exists.

application/json · object

Example: Capture payment id already used

Duplicate capture identifier handling.

JSON
{
  "message": "The merchant unique id already exists."
}

400 Invalid preauth reference.

application/json · object

Example: Capture exceeds the remaining hold

Keep the amount-bearing request alongside the refusal; the error scenario teaches a constraint.

JSON
{
  "message": "Invalid payment amount. Cannot capture payment more than the preauth remaining amount."
}

403 Invalid permission.

application/json · object

404 Unable to find the preauth by the preauth reference provided.

application/json · object

500 Something went wrong. Preauth may or may not be captured.

application/json · object

Example request (cURL, sandbox host)

cURL
curl -X POST 'https://api.sandbox.zenpay.com.au/v2/preauths/{preauthReference}/captures' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Content-Type: application/json' \
  -d '{
  "merchantUniquePaymentId": "capture-over-4505624413024",
  "paymentAmount": 100,
  "sendPaymentConfirmation": false
}'

Void a preauthorization#

PUT/v2/preauths/{preauthReference}/voids

View this endpoint in the original docs

Voids the specified preauthorization.

Authentication: Api-Key + BasicAuth

Parameters

NameInTypeDescription
preauthReference requiredpathstring

The unique reference for the preauthorization.

Responses

200 Preauth has been voided.

application/json · object (VoidCardResponse)

Example: Preauth voided

Shows the successful release operation; no request body is sent.

JSON
{
  "preauthReference": "247445",
  "status": "Successful"
}

400 Invalid preauth reference.

application/json · object

Example: Preauth already voided

Shows a state-dependent refusal when repeating the action.

JSON
{
  "message": "Incorrect preauth status: Cancelled."
}

403 Invalid permission.

application/json · object

404 Unable to find the preauth by the preauth reference provided.

application/json · object

500 Something went wrong. Preauth may or may not be voided.

application/json · object

Example request (cURL, sandbox host)

cURL
curl -X PUT 'https://api.sandbox.zenpay.com.au/v2/preauths/{preauthReference}/voids' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Accept: application/json'
Need help with your integration?Talk to the Zenith Integrations Team.
Email integrationsTalk to us