POI Device Prompts
There are several variables available to customize the POI Device flow on a per transaction basis. All prompts have a default value (true or false). Not all prompts work together, so see below for an explanation.
- Keyed Entry: Using this prompt will provide the cardholder the option to key in their card if desired or if inserting/swiping is not possible for some reason (bad chip, magstripe for example.)
- CVV Entry: When prompting for Keyed entry, specify whether you wish the cardholder to also enter their CVV or not. This is true by default.
- Signature Prompting: When inserting/dipping a chip card, signature prompting may be ignored in favor of the chip card communication with the POI Device. For example if the chip card determines that pin entry is required, signature will not be prompted even if sent as 'true'.
- Amount Confirmation: Using this prompt will provide the cardholder the option to confirm the amount being charged or not. This is false by default.
- Tipping:If prompting for tip, you may set a tip amount via API or allow the customer to enter/select an amount on the POI device itself. Quicktip amount options can be customized as well. See below:
- QuickTip Amounts and Percentages: When sending custom quicktip amounts via API, poi_prompt_tip must be sent as 'true'.Values will be displayed in the order they are provided. Values beyond 3-4 (depending on the device) will be ignored. Example: If the following is sent: poi_prompt_quicktip_amounts: 1.00,2.00,3.00,4.00 - the '4.00' amount will be ignored as the device only has space for 3 custom amounts.
POI Device Prompting Request Details
Variable | Description |
|---|---|
tip | The final tip amount, included in the transaction amount, associated with the purchase.Format: x.xx |
poi_prompt_tip | When set to 'true', will allow the cardholder to type in a tip amount via the POI Device. When sent in with the 'tip' value, this will show a confirmation of the tip value. If poi_prompt_quicktip_amounts or poi_prompt_quicktip_percentages have been specified then the cardholder will be prompted with a list of values. Format: boolean (true/false) Default: false |
poi_prompt_quicktip_amounts | Show an on-screen list of quick tip amount options when tipping via the POI Device. Invalid when sent with poi_prompt_tip set to 'false'. Sending an empty value for this parameter will result in an automatically generated list of values sent to the POI Device. This POI Device Prompt is not supported with Miura devices. Format: X.XX, comma delimited up to 4 options. Example: 1.50,3.00,4.50 |
poi_prompt_quicktip_percentages | Show an on-screen list of quick tip percentage options when tipping via the POI Device. Invalid when sent with poi_prompt_tip set to 'false'. Cannot be sent with poi_prompt_quicktip_amounts. Sending an empty value for this parameter will result in an automatically generated list of values sent to the POI Device. Format: XX.XX, comma delimited up to 4 options. Example: 10.00,15.50,20.34 |
poi_enable_keyed | When set to 'true', provides the option to key-in the card details via the POI Device. Format: boolean (true/false) Default: false |
poi_require_keyed | When set to 'true', forces the cardholder to key-in the card details via the POI Device. This prompt does not allow any other entry method when set.Note: Cannot be set to 'true' when poi_enable_keyed is also set to 'true'. Format: boolean (true/false) Default: false |
poi_keyed_type | Specifies the type of keyed transaction. If this variable is not specified and either poi_enable_keyed or poi_require_keyed is 'true' then defaults to 'cnp'.Format: Any one of 'cnp', 'card_present', 'ecommerce', 'mail_order', 'telephone_order' Default: cnp when either poi_enable_keyed or poi_require_keyed is 'true' |
poi_prompt_cvv | When set to 'false', the CVV code will not be requested from the customer via the POI Device on a keyed transaction. Invalid when sent with poi_enable_keyed set to 'false' or when poi_enable_keyed is not sent. Format: boolean (true/false) Default: true |
poi_prompt_zip | When set to 'true', will enforce zip code/postal entry via the POI Device. Note: Entry on the device will override a zip code sent via API in the initial request. Format: boolean (true/false) Default: false |
poi_prompt_amount_confirmation | When set to 'true', will force the user to confirm the amount being charged via the POI Device. Format: boolean (true/false) Default: false |
poi_prompt_signature | When set to 'true', will force the user to sign via the POI Device where supported. When set to 'false', will skip the signature capture step for magstripe transactions. Will be overridden via Chip Card/POI Device interaction when applicable. Format: boolean (true/false) Default: true |
poi_request | If you wish to reset the POI Device before a transaction has been processed, but after the transaction has been requested, you may request a cancellation. This does NOT guarantee the transaction can be cancelled on the device. If the authorization has already begun, you will need to void the transaction after it has completed, assuming it was approved. You must provide the POI Device ID in the request with this prompt. Value: 'cancellation' |
poi_automatic_fall_forward | When set to 'true', will enable Fall Forward (EMV Contactless upgrade to EMV Contact) in-line via the POI Device where supported. When set to 'false', transactions will need to be restarted when tapped cards that are rejected by the Issuer require a contact/EMV insert to occur. Format: boolean (true/false) Default: true |
poi_enable_void | Enable voids as a part of the transaction flow. For example if the cardholder removes the card after the transaction has been approved but before the transaction can be finalized, the transaction will be voided. Format: boolean (true/false) Default: false |
Examples:
Customer Input Tip Prompt: With the following request, the specified POI device will prompt the cardholder to enter the amount they wish to tip.
Note: The default QuickTip options are a calculation of the total amount using the following percentages: 15%, 18%, and 20%. The final amounts will appear as dollar amounts on the device screen.
...type=sale&poi_device_id=0b3043ca-5764-4edc-b720-b652bdf73c9e
&poi_prompt_tip=true&amount=11.00Set Tip Prompt: With the following request, the specified POI device will prompt the cardholder to confirm they wish to tip the amount included with the transaction request (in this example, 1.00). This value will be added onto the amount sent with the transaction request.
...type=sale&poi_device_id=0b3043ca-5764-4edc-b720-b652bdf73c9e
&poi_prompt_tip=true&tip=1.00&amount=11.00QuickTip Customization: With the following request, the specified POI device will display custom amounts or percentages sent in the request. This can be provided with or without a specific tip amount, but must be provided with the basic tip prompt of poi_prompt_tip=true.
QuickTip Amounts:: With the below example, on Ingenico devices the cardholder would be prompted to confirm the 1.00 amount, but will be able to choose from a list of the provided amounts. Selecting the 'Other' on-screen option will allow for them to enter a custom amount.
...type=sale&poi_device_id=0b3043ca-5764-4edc-b720-b652bdf73c9e
&poi_prompt_tip=true&tip=1.00&poi_prompt_quicktip_amounts=1.00,3.00,5.00&...QuickTip Percentages:: With the below example, on Ingenico devices the cardholder would be prompted to confirm the 1.00 amount, but will be able to choose from a list of the provided percentages. Selecting the 'Other' on-screen option will allow for them to enter a custom amount.
...type=sale&poi_device_id=0b3043ca-5764-4edc-b720-b652bdf73c9e
&poi_prompt_tip=true&tip=1.00&poi_prompt_quicktip_percentages=10.00,20.00,25.00&...Enabling Keyed Entry: With the following request, the specified POI device will show the standard 'Insert or Swipe' message, but also have the option to 'Enter Card' by selecting the F1 key on the device. If 'Enter Card' is selected, the cardholder will be prompted to enter their card number, the expiration date, and the CVV code from the back of the card. This is set to 'false' by default, so it only needs to be sent if you want this option available for use.
...type=sale&poi_device_id=0b3043ca-5764-4edc-b720-b652bdf73c9e
&poi_enable_keyed=true...Enforcing Keyed Entry: With the following request, the specified POI device will prompt the cardholder to enter their card number, the expiration date, and the CVV code from the back of the card. This is set to 'false' by default, so it only needs to be sent if you want to only allow keyed entry rather than give the 'option' to.
...type=sale&poi_device_id=0b3043ca-5764-4edc-b720-b652bdf73c9e
&poi_require_keyed=true...CVV Prompt w/ Keyed Entry: With the following request, the POI device will not display the CVV field when keying in a card to the POI Device. CVV prompting is 'true' by default.
...type=sale&poi_device_id=0b3043ca-5764-4edc-b720-b652bdf73c9e
&poi_enable_keyed=true&poi_prompt_cvv=false...Signature Confirmation: With the following request, the specified POI device will either enforce a digital signature capture or show a message to capture the signature manually if on a device with no signature capture capabilities.
Note: This prompt will only be honored on magstripe transactions as signature capture enforcement is controlled on EMV transactions by the chip itself which cannot be overridden.
...type=sale&poi_device_id=0b3043ca-5764-4edc-b720-b652bdf73c9e
&poi_prompt_signature=true...Amount Confirmation: With the following request, the specified POI device will either enforce a cardholder to "confirm" the amount shown on the POI Device screen or not. This is 'false' by default, so it must be sent in order to show the amount confirmation prompts.
...type=sale&poi_device_id=0b3043ca-5764-4edc-b720-b652bdf73c9e
&poi_prompt_amount_confirmation=true...Device Reset/Cancellation: With the following request, the current transaction request on specified POI device will be cancelled as long as authorization has not already begun.
...poi_request=cancellation
&poi_device_id=0b3043ca-5764-4edc-b720-b652bdf73c9e......response=1
&responsetext=Transaction cancellation requested. If the transaction cannot be cancelled, you must process a void request once the transaction is complete.
&...&response_code=100...Updated 16 days ago