Sale with On-Receipt Tipping {#sis-pymnt-svcs-sale-on-receipt-tip-intro}
========================================================================

Use this information to process a sale with on-receipt tipping when the app is in Local mode. After the original transaction is pre-authorized, the customer writes the tip or total amount on the printed receipt. A follow-on tip adjust request must be sent within 24 hours to capture the transaction. For more information, see [Tip Adjust](/docs/cybs/en-us/sis-pax/integration/all/rest/sis-pax/semi-integrated-pymnt-svcs-intro/sis-pymnt-svcs-sale-on-receipt-tip-intro/sis-pymnt-svcs-tip-adjust-on-receipt-sale-intro.md "").

> WARNING
> By using this feature, you assume the risk of overcaptures being declined and increased chargebacks, so use it only when necessary. Process sales with on-reader tipping, whenever possible. For more information, see [Sale with On-Reader Tipping](/docs/cybs/en-us/sis-pax/integration/all/rest/sis-pax/semi-integrated-pymnt-svcs-intro/sis-local-sale-on-reader-tip-api-intro.md "").

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 a Sale with On-Receipt Tipping {#sis-pymnt-svcs-sale-on-receipt-tip-api-reqfields}
======================================================================================================

type
:
Set the value to `PaymentRequest`.

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 to `false`.

askForTip
:
Set the value to `ON_RECEIPT`.

REST Example: Sale with On-Receipt Tipping {#sis-pymnt-svcs-sale-on-receipt-tip-api-ex-rest}
============================================================================================

Request

```
{
      "type" : "PaymentRequest",
      "merchantReferenceCode" : "1ce594be142142f4913cca805830a176",
      "amountDetails" : {
        "amount" : "20.00",
        "currency" : "USD"
      },
      "capture" : false,
      "askForTip" : "ON_RECEIPT"
}
```

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" : "c6174c80b81f4413a4b9f2065c5431c7",
    "merchantReferenceCode" : "1ce594be142142f4913cca805830a176",
    "submitTimeUtc" : "2024-03-20T09:19:41+0000",
    "captured" : false,
    "amountDetails" : {
      "currency" : "USD",
      "amount" : "20.00",
      "capturedAmount" : "20.00",
      "refundableAmount" : "20.00"
    }
  },
  "processingDetails" : {
    "status" : "APPROVED",
    "verificationMethod" : "NONE",
    "entryMode" : "NFC_ICC",
    "card" : {
      "expirationMonth" : "12",
      "expirationYear" : "2025",
      "type" : "VISA",
      "maskedPan" : "476173XXXXXX0119",
      "countryCode" : "840"
    }
  },
  "additionalInformation" : {
    "instrumentId" : "7030000000022690119",
    "requestId" : "7109263864326505004007"
  },
  "linkedOperations" : [ ],
  "tipAdjustStatus" : "ADJUSTABLE",
  "receipts" : {
    "merchantReceipt" : {
      "preformattedReceipt" : "Merchant Receipt\nCP Test\nSample Street\n55555 New York\nUnited States\n1234567\n\nSale\n$20.00\nPlease retain receipt!\n\nCard: Payworks VISA\nAccount: **** **** **** 0119\nEntry Mode: Contactless\nAID: A0000000031010\nVerification: None\n\nAuthorization: 002000\nMerchant ID: **37599\nTerminal ID: ****0063\n\n\nc6174c80b81f4413a4b9f2065c5431c7\n\n\n\n10:19:46: 20/03/2024\n\n\n\nTIP:\n___________________\n\nTOTAL:\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" : "55555"
          },
          "MERCHANT_DETAILS_CITY" : {
            "label" : "City",
            "value" : "New York"
          },
          "MERCHANT_DETAILS_COUNTRY" : {
            "label" : "Country",
            "value" : "United States"
          },
          "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" : "002000"
          },
          "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" : "c6174c80b81f4413a4b9f2065c5431c7"
          },
          "AMOUNT_AND_CURRENCY" : {
            "label" : "Amount",
            "value" : "$20.00"
          },
          "DATE" : {
            "label" : "Date",
            "value" : "20/03/2024"
          },
          "TIME" : {
            "label" : "Time",
            "value" : "10:19:46"
          },
          "STATUS_TEXT" : {
            "label" : "Information",
            "value" : "Please retain receipt!"
          }
        },
        "signatureLineRequired" : false,
        "tipLineRequired" : true,
        "totalLineRequired" : true
      }
    },
    "customerReceipt" : {
      "preformattedReceipt" : "Cardholder Receipt\nCP Test\nSample Street\n55555 New York\nUnited States\n1234567\n\nSale\n$20.00\nPlease retain receipt!\n\nCard: Payworks VISA\nAccount: **** **** **** 0119\nEntry Mode: Contactless\nAID: A0000000031010\nVerification: None\n\nAuthorization: 002000\nMerchant ID: **37599\nTerminal ID: ****0063\n\n\nc6174c80b81f4413a4b9f2065c5431c7\n\n\n\n10:19:46: 20/03/2024\n\n\n\nTIP:\n___________________\n\nTOTAL:\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" : "55555"
          },
          "MERCHANT_DETAILS_CITY" : {
            "label" : "City",
            "value" : "New York"
          },
          "MERCHANT_DETAILS_COUNTRY" : {
            "label" : "Country",
            "value" : "United States"
          },
          "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" : "002000"
          },
          "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" : "c6174c80b81f4413a4b9f2065c5431c7"
          },
          "AMOUNT_AND_CURRENCY" : {
            "label" : "Amount",
            "value" : "$20.00"
          },
          "DATE" : {
            "label" : "Date",
            "value" : "20/03/2024"
          },
          "TIME" : {
            "label" : "Time",
            "value" : "10:19:46"
          },
          "STATUS_TEXT" : {
            "label" : "Information",
            "value" : "Please retain receipt!"
          }
        },
        "signatureLineRequired" : false,
        "tipLineRequired" : true,
        "totalLineRequired" : true
      }
    }
  }
}
```

Response to an Unsuccessful Request  
When the request is unsuccessful, you receive an error response with details.

```
{
      "type": "ErrorResponse",
      "message": "Error message to display.",
      "developerDescription": "Detailed description of error."
}
```

Tip Adjust {#sis-pymnt-svcs-tip-adjust-on-receipt-sale-intro}
=============================================================

Use this information to process a tip adjust when the app is in Local Mode mode. This follow-on transaction is required when processing an on-receipt tipping transaction. The tip adjust request must be sent within 24 hours to capture the transaction.  
After the original transaction is pre-authorized, the customer writes the tip or total amount on the printed receipt. A follow-on tip adjust request is then sent to capture the additional tip amount. This transaction is also referred to as an *overcapture* . For more information, see [Sale with On-Receipt Tipping](/docs/cybs/en-us/sis-pax/integration/all/rest/sis-pax/semi-integrated-pymnt-svcs-intro/sis-pymnt-svcs-sale-on-receipt-tip-intro.md "").

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 a Tip Adjust {#sis-pymnt-svcs-tip-adjust-on-receipt-sale-api-reqfields}
===========================================================================================

type
:
Set the value to `TipAdjustRequest`.

transactionId
:
Set the value to the id field value from the original transaction.

amountDetails.amount
:
Set the value to the transaction amount.

amountDetails.currency
:
Set the value to the currency code.

REST Example: Tip Adjust {#sis-pymnt-svcs-tip-adjust-on-receipt-sale-api-ex-rest}
=================================================================================

Request

```
{
      "type": "TipAdjustRequest",
      "transactionId": "c6174c80b81f4413a4b9f2065c5431c7",
      "amountDetails": {
        "amount": "4.00",
        "currency": "USD"
      }
}
```

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" : "TipAdjustResponse",
  "message" : "Payment approved",
  "transactionDetails" : {
    "id" : "c6174c80b81f4413a4b9f2065c5431c7",
    "merchantReferenceCode" : "1ce594be142142f4913cca805830a176",
    "submitTimeUtc" : "2024-03-20T09:19:41+0000",
    "captured" : true,
    "amountDetails" : {
      "currency" : "USD",
      "amount" : "24.00",
      "capturedAmount" : "24.00",
      "refundableAmount" : "24.00",
      "includedTipAmount" : "4.00"
    }
  },
  "processingDetails" : {
    "status" : "APPROVED",
    "verificationMethod" : "NONE",
    "entryMode" : "NFC_ICC",
    "card" : {
      "expirationMonth" : "12",
      "expirationYear" : "2025",
      "type" : "VISA",
      "maskedPan" : "476173XXXXXX0119",
      "countryCode" : "840"
    }
  },
  "additionalInformation" : {
    "instrumentId" : "7030000000022690119",
    "requestId" : "7109265975966653104007"
  },
  "linkedOperations" : [ ],
  "tipAdjustStatus" : "ADJUSTED",
  "receipts" : {
    "merchantReceipt" : {
      "preformattedReceipt" : "Merchant Receipt\nCP Test\nSample Street\n55555 New York\nUnited States\n1234567\n\nCapture\nPurchase Amount: $20.00\nTip Amount: $4.00\nTotal Amount: $24.00\nPlease retain receipt!\n\nCard: Payworks VISA\nAccount: **** **** **** 0119\nEntry Mode: Contactless\nAID: A0000000031010\nVerification: None\n\nAuthorization: 002000\nMerchant ID: **37599\nTerminal ID: ****7478\n\n\nc6174c80b81f4413a4b9f2065c5431c7\n\n10:23:17: 20/03/2024\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" : "55555"
          },
          "MERCHANT_DETAILS_CITY" : {
            "label" : "City",
            "value" : "New York"
          },
          "MERCHANT_DETAILS_COUNTRY" : {
            "label" : "Country",
            "value" : "United States"
          },
          "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" : "002000"
          },
          "CLEARING_DETAILS_MERCHANT_IDENTIFIER" : {
            "label" : "Merchant ID",
            "value" : "**37599"
          },
          "CLEARING_DETAILS_TERMINAL_ID" : {
            "label" : "Terminal ID",
            "value" : "****7478"
          },
          "RECEIPT_TYPE" : {
            "label" : "Receipt Type",
            "value" : "Merchant Receipt"
          },
          "TRANSACTION_TYPE" : {
            "label" : "Type",
            "value" : "Capture"
          },
          "SUBJECT" : {
            "label" : "Description",
            "value" : ""
          },
          "IDENTIFIER" : {
            "label" : "PWID",
            "value" : "c6174c80b81f4413a4b9f2065c5431c7"
          },
          "AMOUNT_AND_CURRENCY" : {
            "label" : "Amount",
            "value" : "$24.00"
          },
          "DATE" : {
            "label" : "Date",
            "value" : "20/03/2024"
          },
          "TIME" : {
            "label" : "Time",
            "value" : "10:23:17"
          },
          "STATUS_TEXT" : {
            "label" : "Information",
            "value" : "Please retain receipt!"
          }
        },
        "signatureLineRequired" : false,
        "tipLineRequired" : false,
        "totalLineRequired" : false
      }
    },
    "customerReceipt" : {
      "preformattedReceipt" : "Cardholder Receipt\nCP Test\nSample Street\n55555 New York\nUnited States\n1234567\n\nCapture\nPurchase Amount: $20.00\nTip Amount: $4.00\nTotal Amount: $24.00\nPlease retain receipt!\n\nCard: Payworks VISA\nAccount: **** **** **** 0119\nEntry Mode: Contactless\nAID: A0000000031010\nVerification: None\n\nAuthorization: 002000\nMerchant ID: **37599\nTerminal ID: ****7478\n\n\nc6174c80b81f4413a4b9f2065c5431c7\n\n10:23:17: 20/03/2024\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" : "55555"
          },
          "MERCHANT_DETAILS_CITY" : {
            "label" : "City",
            "value" : "New York"
          },
          "MERCHANT_DETAILS_COUNTRY" : {
            "label" : "Country",
            "value" : "United States"
          },
          "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" : "002000"
          },
          "CLEARING_DETAILS_MERCHANT_IDENTIFIER" : {
            "label" : "Merchant ID",
            "value" : "**37599"
          },
          "CLEARING_DETAILS_TERMINAL_ID" : {
            "label" : "Terminal ID",
            "value" : "****7478"
          },
          "RECEIPT_TYPE" : {
            "label" : "Receipt Type",
            "value" : "Cardholder Receipt"
          },
          "TRANSACTION_TYPE" : {
            "label" : "Type",
            "value" : "Capture"
          },
          "SUBJECT" : {
            "label" : "Description",
            "value" : ""
          },
          "IDENTIFIER" : {
            "label" : "PWID",
            "value" : "c6174c80b81f4413a4b9f2065c5431c7"
          },
          "AMOUNT_AND_CURRENCY" : {
            "label" : "Amount",
            "value" : "$24.00"
          },
          "DATE" : {
            "label" : "Date",
            "value" : "20/03/2024"
          },
          "TIME" : {
            "label" : "Time",
            "value" : "10:23:17"
          },
          "STATUS_TEXT" : {
            "label" : "Information",
            "value" : "Please retain receipt!"
          }
        },
        "signatureLineRequired" : false,
        "tipLineRequired" : false,
        "totalLineRequired" : false
      }
    }
  }
}
```

Response to an Unsuccessful Request  
When the request is unsuccessful, you receive an error response with details.

```
{
      "type": "ErrorResponse",
      "message": "Error message to display.",
      "developerDescription": "Detailed description of error."
}
```