PreAuth – Trust Payments

The PreAuth transaction processes a standard authorisation transaction to hold funds from the customer's card. Follow this with a Capture to complete the transaction.

Endpoint : /preauth

The topuptoken returned in the response can be used to increase the amount authorized at a later time. Submit the value in the field topuptoken in a new PreAuth request and the new amount specified will be added to the total pre-authorized amount. This functionality is currently only limited to some Visa/Mastercard issuers. If the issuer doesn't support top ups, the transaction will decline.

PreAuth Request

{
"amount":"60.00",
"refid":"89045432",
"siteid":"123456",
"terminalserialnumber":"6789654678",
"txndate":"2023-02-01:16:13:20",
"type":"preauth",
"wait":"y"
}

Request field specification

	Field	Format	Description
Required	amount	String e.g. 20.00	The amount to be pre-authorised for the transaction in main units (e.g. £20 would be submitted as 20.00). Funds are not debited from the customer's card until a Capture request is processed.
Required	refid	String (min length: 1) e.g. 1234567890	The unique identifier to the transaction being submitted. (The value submitted must be unique within the scope of your own transactions)
Required	siteid	String (min length: 1) e.g. 1234	Unique identification code supplied by Trust Payments.
Required	terminalserialnumber	String (min length: 1) e.g. 1234567890	The unique terminal identifier for the PIN Entry Device (PED) supplying the card details. This is the serial number of the PED.
Required	txndate	String e.g. 2020-03-01:10:20:05	Unique timestamp for the transaction.
Required	type	String	You must submit "preauth", as shown in the request example.
Required	wait	String	The following two values can be submitted: y – TRU Link will wait for the terminal before returning a response, typically with resultcode of either "Approved" or "Declined". n – TRU Link will immediately return a response with resultcode of "Pending". The status of the transaction can be checked at a later time by submitting a Status request via TRU Link.
Optional	topuptoken	String e.g. 1234567890	A token that links the previous authorisation to this one. Allows the funds reserved to be increased.

PreAuth Response

{
"amount":"60.00",
"authcode":"abc1234",
"cardtype":"Visa",
"expiry":"2023-02-08:04:13:20",
"finalamount":"60.00",
"last4":"0026",
"merchantreceipt":"Sample output",
"receipt":"Sample output",
"refid":"123456789876543212345",
"resultcode":"Approved",
"siteid":"123456",
"terminalserialnumber":"6789654678",
"topuptoken":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

Response field specification

	Field	Format	Description
Returned	amount	String e.g. 20.00	The original full amount authorised for the transaction in main units (e.g. £20 would be returned as 20.00). Note: The amount may differ from that submitted in the request due to changes made by the customer during checkout (e.g. addition of a tip).
Returned	refid	String e.g. 1234567890	The unique identifier assigned to the transaction submitted.
Returned	resultcode	String e.g. Approved	The result of the transaction from the acquirer. Possible values are: Approved Cancelled Connection Timeout Declined Error Pending Terminal Busy
Returned	siteid	String e.g. 1234	Unique code to identify the Trust Payments site used to process the request.
Returned	terminalserialnumber	String e.g. 1234567890	The unique terminal identifier for the PIN Entry Device (PED) supplying the card details.
Conditional	authcode	String e.g. 1234567890	The authorisation code of the transaction. Only returned if transaction was authorised.
Conditional	cardtype	String e.g. Visa	Contains the card type used for this transaction (e.g. "VISA"). Returned if available.
Conditional	error	String e.g. Invalid amount	The field returns details of an error if a request was not processed successfully. Info on error handling. Only returned if an error has occurred.
Conditional	errorcode	Integer e.g. 1006	This code helps you identify the error if a request was not processed successfully. Info on error handling. Only returned if an error has occurred.
Conditional	expiry	String e.g. 2023-02-08:04:13:20	The expiry date and time for the authorisation. After this time, it is not possible to topup or capture. Returned if available.
Conditional	finalamount	String e.g. 20.00	The final amount authorised for the transaction in main units (e.g. £20 would be returned as 20.00). Note: The finalamount will include any changes made by the customer during checkout (e.g. addition of a tip). Returned if the finalamount differs from the original amount.
Conditional	last4	String e.g. 6789	The last 4 digits of the customer debit/credit card used to facilitate the transaction. Returned if available.
Conditional	merchantreceipt	String e.g. Merchant Receipt	Contains merchant receipt data that can be used for printing on the ePOS. Returned if available.
Conditional	message	String e.g. Message	Response message from issuer when card is declined. Only returned in a decline response.
Conditional	receipt	String e.g. Customer Receipt	Contains cardholder receipt data that can be used for printing on the ePOS. Returned if available.
Conditional	topuptoken	String e.g. 1234567890	A token that links the previous authorisation to this one. Allows the funds reserved to be increased. Returned if available.