On This Page
Pre-Authorization
Use the information in this section to process a pre-authorization for an initial amount
in Local mode. A pre-authorization transaction places a temporary hold on the customer's
payment card, which can be captured at a later time.
Most authorizations expire in 5 to 7 days. The issuing bank sets the length of time
before expiration. When an authorization expires with the issuing bank, your bank or
processor might require you to re-submit an authorization request and include a request
for capture in the same message. For more information, see Capture.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for a Pre-Authorization
- type
- Set the value toPaymentRequest.
- merchantReferenceCode
- Set the value to a unique, user-defined reference code. The code can consist of up to 50 alphanumeric characters, underscores (_), and dashes (-). Avoid using formatting that resembles a telephone number (XXX-XXX-XXXX) or a Social Security number (XXX-XX-XXXX).
- amountDetails.amount
- Set the value to the transaction amount.
- amountDetails.currency
- Set the value to the currency code.
- capture
- Set the value tofalse.
REST Example: Pre-Authorization
Request
{ "type" : "PaymentRequest", "merchantReferenceCode" : "47bd9ed54f3f4bfabb9d3ee94cfa3008", "amountDetails" : { "amount" : "1.00", "currency" : "GBP" }, "capture" : false }
Mid-Transaction Status Updates
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
{ "type": "TransactionStatusResponse", "message": "Status update to display.", "canBeAborted": true/false }
Response to a Successful Request
{ "type" : "PaymentResponse", "message" : "Payment approved", "transactionDetails" : { "id" : "e43069fbf85543659e478edd8d50f244", "merchantReferenceCode" : "47bd9ed54f3f4bfabb9d3ee94cfa3008", "submitTimeUtc" : "2023-12-01T20:38:14+0000", "captured" : false, "amountDetails" : { "currency" : "GBP", "amount" : "1.00", "capturedAmount" : "0.00", "refundableAmount" : "1.00" } }, "processingDetails" : { "status" : "APPROVED", "verificationMethod" : "NONE", "entryMode" : "NFC_ICC", "card" : { "expirationMonth" : "12", "expirationYear" : "2025", "type" : "VISA", "maskedPan" : "476173XXXXXX0119", "countryCode" : "840" } }, "additionalInformation" : { "instrumentId" : "7030000000022690119", "requestId" : "7014630972006630604008" }, "linkedOperations" : [ ], "receipts" : { "merchantReceipt" : { "preformattedReceipt" : "Merchant Receipt\nCP Test\nSample Street\nUB3 2EA London\nUnited Kingdom\n1234567\n\nAuth only\n£1.00\n\n\nPlease retain receipt!\n\n\nCard: Payworks VISA\nAccount: **** **** **** 0119\nEntry Mode: Contactless\nAID: A0000000031010\nVerification: None\n\nAuthorization: 938242\nMerchant ID: **37599\nTerminal ID: ****0063\n\ne43069fbf85543659e478edd8d50f244\n21:38:18: 01/12/2023\n\n\n", "receiptData" : { "lines" : { "MERCHANT_DETAILS_PUBLIC_NAME" : { "label" : "Name", "value" : "CP Test" }, "MERCHANT_DETAILS_ADDRESS" : { "label" : "Address", "value" : "Sample Street" }, "MERCHANT_DETAILS_ZIP" : { "label" : "Zip", "value" : "UB3 2EA" }, "MERCHANT_DETAILS_CITY" : { "label" : "City", "value" : "London" }, "MERCHANT_DETAILS_COUNTRY" : { "label" : "Country", "value" : "United Kingdom" }, "MERCHANT_DETAILS_CONTACT" : { "label" : "Contact", "value" : "1234567" }, "MERCHANT_DETAILS_ADDITIONAL_INFORMATION" : { "label" : "Additional Information", "value" : "" }, "PAYMENT_DETAILS_SCHEME_OR_LABEL" : { "label" : "Card", "value" : "Payworks VISA" }, "PAYMENT_DETAILS_MASKED_ACCOUNT" : { "label" : "Account", "value" : "**** **** **** 0119" }, "PAYMENT_DETAILS_EMV_APPLICATION_ID" : { "label" : "AID", "value" : "A0000000031010" }, "PAYMENT_DETAILS_SOURCE" : { "label" : "Entry Mode", "value" : "Contactless" }, "PAYMENT_DETAILS_CUSTOMER_VERIFICATION" : { "label" : "Verification", "value" : "None" }, "CLEARING_DETAILS_AUTHORIZATION_CODE" : { "label" : "Authorization", "value" : "938242" }, "CLEARING_DETAILS_MERCHANT_IDENTIFIER" : { "label" : "Merchant ID", "value" : "**37599" }, "CLEARING_DETAILS_TERMINAL_ID" : { "label" : "Terminal ID", "value" : "****0063" }, "RECEIPT_TYPE" : { "label" : "Receipt Type", "value" : "Merchant Receipt" }, "TRANSACTION_TYPE" : { "label" : "Type", "value" : "Auth only" }, "SUBJECT" : { "label" : "Description", "value" : "" }, "IDENTIFIER" : { "label" : "PWID", "value" : "e43069fbf85543659e478edd8d50f244" }, "AMOUNT_AND_CURRENCY" : { "label" : "Amount", "value" : "£1.00" }, "DATE" : { "label" : "Date", "value" : "01/12/2023" }, "TIME" : { "label" : "Time", "value" : "21:38:18" }, "STATUS_TEXT" : { "label" : "Information", "value" : "Please retain receipt!" } }, "signatureLineRequired" : false } }, "customerReceipt" : { "preformattedReceipt" : "Cardholder Receipt\nCP Test\nSample Street\nUB3 2EA London\nUnited Kingdom\n1234567\n\nAuth only\n£1.00\n\n\nPlease retain receipt!\n\n\nCard: Payworks VISA\nAccount: **** **** **** 0119\nEntry Mode: Contactless\nAID: A0000000031010\nVerification: None\n\nAuthorization: 938242\nMerchant ID: **37599\nTerminal ID: ****0063\n\ne43069fbf85543659e478edd8d50f244\n21:38:18: 01/12/2023\n\n\n", "receiptData" : { "lines" : { "MERCHANT_DETAILS_PUBLIC_NAME" : { "label" : "Name", "value" : "CP Test" }, "MERCHANT_DETAILS_ADDRESS" : { "label" : "Address", "value" : "Sample Street" }, "MERCHANT_DETAILS_ZIP" : { "label" : "Zip", "value" : "UB3 2EA" }, "MERCHANT_DETAILS_CITY" : { "label" : "City", "value" : "London" }, "MERCHANT_DETAILS_COUNTRY" : { "label" : "Country", "value" : "United Kingdom" }, "MERCHANT_DETAILS_CONTACT" : { "label" : "Contact", "value" : "1234567" }, "MERCHANT_DETAILS_ADDITIONAL_INFORMATION" : { "label" : "Additional Information", "value" : "" }, "PAYMENT_DETAILS_SCHEME_OR_LABEL" : { "label" : "Card", "value" : "Payworks VISA" }, "PAYMENT_DETAILS_MASKED_ACCOUNT" : { "label" : "Account", "value" : "**** **** **** 0119" }, "PAYMENT_DETAILS_EMV_APPLICATION_ID" : { "label" : "AID", "value" : "A0000000031010" }, "PAYMENT_DETAILS_SOURCE" : { "label" : "Entry Mode", "value" : "Contactless" }, "PAYMENT_DETAILS_CUSTOMER_VERIFICATION" : { "label" : "Verification", "value" : "None" }, "CLEARING_DETAILS_AUTHORIZATION_CODE" : { "label" : "Authorization", "value" : "938242" }, "CLEARING_DETAILS_MERCHANT_IDENTIFIER" : { "label" : "Merchant ID", "value" : "**37599" }, "CLEARING_DETAILS_TERMINAL_ID" : { "label" : "Terminal ID", "value" : "****0063" }, "RECEIPT_TYPE" : { "label" : "Receipt Type", "value" : "Cardholder Receipt" }, "TRANSACTION_TYPE" : { "label" : "Type", "value" : "Auth only" }, "SUBJECT" : { "label" : "Description", "value" : "" }, "IDENTIFIER" : { "label" : "PWID", "value" : "e43069fbf85543659e478edd8d50f244" }, "AMOUNT_AND_CURRENCY" : { "label" : "Amount", "value" : "£1.00" }, "DATE" : { "label" : "Date", "value" : "01/12/2023" }, "TIME" : { "label" : "Time", "value" : "21:38:18" }, "STATUS_TEXT" : { "label" : "Information", "value" : "Please retain receipt!" } }, "signatureLineRequired" : false } } } }
Response to an Unsuccessful Request
When the request is unsuccessful, you will receive an error response with details.
{ "type": "ErrorResponse", "message": "Error message to display.", "developerDescription": "Detailed description of error." }