On This Page
Processing a Sale with On-Reader Tipping
This section describes how to process a sale with on-reader tipping in Local
mode. At the start of each transaction, the terminal prompts the customer to add a tip
by showing suggested tip amounts. The customer selects or enters a tip amount on the
terminal before presenting their payment card.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{terminal IP address:port number}/
Production:
wss://{terminal IP address:port number}/
Required Fields for Processing a Sale with On-Reader Tipping
- type
- Set this field toPaymentRequest.
- merchantReferenceCode
- Set this field 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 this field to the transaction amount.
- amountDetails.currency
- Set this field to the currency code.
- askForTip
- Set this field toON_DEVICE.
REST Example: Processing a Sale with On-Reader Tipping
Request
{ "type" : "PaymentRequest", "merchantReferenceCode" : "adf0fa5ca70d462ba5fc0249436b656c", "amountDetails" : { "amount" : "5.00", "currency" : "GBP" }, "askForTip" : "ON_DEVICE" }
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" : "55678c8b152046f7b1d77fd2286ce392", "merchantReferenceCode" : "adf0fa5ca70d462ba5fc0249436b656c", "submitTimeUtc" : "2023-12-01T21:01:23+0000", "captured" : true, "amountDetails" : { "currency" : "GBP", "amount" : "6.00", "capturedAmount" : "6.00", "refundableAmount" : "6.00", "includedTipAmount" : "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" : "7014644863036208304012" }, "linkedOperations" : [ ], "receipts" : { "merchantReceipt" : { "preformattedReceipt" : "Merchant Receipt\nCP Test\nSample Street\nUB3 2EA London\nUnited Kingdom\n1234567\n\nSale\nPurchase Amount: £5.00\nTip Amount: £1.00\nTotal Amount: £6.00\n\n\nPlease retain receipt!\n\n\nCard: Payworks VISA\nAccount: **** **** **** 0119\nEntry Mode: Contactless\nAID: A0000000031010\nVerification: None\n\nAuthorization: 938252\nMerchant ID: **37599\nTerminal ID: ****0063\n\n55678c8b152046f7b1d77fd2286ce392\n22:01:27: 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" : "938252" }, "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" : "Sale" }, "SUBJECT" : { "label" : "Description", "value" : "" }, "IDENTIFIER" : { "label" : "PWID", "value" : "55678c8b152046f7b1d77fd2286ce392" }, "AMOUNT_AND_CURRENCY" : { "label" : "Amount", "value" : "£6.00" }, "DATE" : { "label" : "Date", "value" : "01/12/2023" }, "TIME" : { "label" : "Time", "value" : "22:01:27" }, "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\nSale\nPurchase Amount: £5.00\nTip Amount: £1.00\nTotal Amount: £6.00\n\n\nPlease retain receipt!\n\n\nCard: Payworks VISA\nAccount: **** **** **** 0119\nEntry Mode: Contactless\nAID: A0000000031010\nVerification: None\n\nAuthorization: 938252\nMerchant ID: **37599\nTerminal ID: ****0063\n\n55678c8b152046f7b1d77fd2286ce392\n22:01:27: 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" : "938252" }, "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" : "Sale" }, "SUBJECT" : { "label" : "Description", "value" : "" }, "IDENTIFIER" : { "label" : "PWID", "value" : "55678c8b152046f7b1d77fd2286ce392" }, "AMOUNT_AND_CURRENCY" : { "label" : "Amount", "value" : "£6.00" }, "DATE" : { "label" : "Date", "value" : "01/12/2023" }, "TIME" : { "label" : "Time", "value" : "22:01:27" }, "STATUS_TEXT" : { "label" : "Information", "value" : "Please retain receipt!" } }, "signatureLineRequired" : false } } } }
Response to an Unsuccessful Request
If the request is unsuccessful, you receive an error response with details.
{ "type": "ErrorResponse", "message": "Error message to display.", "developerDescription": "Detailed description of error." }