Outlines passing tender options (settings that change how a transaction is processed) with a PaymentRequest
and things to consider when using them.
Tender options can be used to modify your payment request. Tender options are passed to the Terminal API using the SaleToAcquirerData
or TransactionConditions
field.
Endpoint
Request
Tender options are passed with a regular PaymentRequest
in the same way as making a basic payment. A PaymentRequest
can include additional form-encoded key-value pairs in the SaleToAcquirerData
field. This can include data to create recurring contracts.
Pass tender options in TransactionConditions
Some tender options can be expressed the The Terminal API directly using ForceEntryMode
, passed in TransactionConditions
.
- If ForceEntryMode is absent, the default entry modes are used.
- If the list includes "Keyed", the terminal will trigger Manual Keyed Entry processing.
- If the list includes "MagStripe", magstripe is used as the POS entry mode.
- If the list does not include "Contactless", contactless will be disabled as a POS entry mode and no contactless option will be presented.
{ "SaleToPOIRequest": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "Payment", "MessageType": "Request", "ServiceID": "0207112225", "SaleID": "POSSystemID12345", "POIID": "MX925-289173817" }, "PaymentRequest": { "SaleData": { "SaleTransactionID": { "TransactionID": "2954", "TimeStamp": "2018-02-07T10:22:25+00:00" } }, "PaymentTransaction": { "AmountsReq": { "Currency": "EUR", "RequestedAmount": 10.99 }, "TransactionConditions": { "ForceEntryMode": [ "Keyed" ] } } } } }
Pass tender options in SaleToAcquirerData
The fields described below are the basic payment fields you specify when making a PaymentRequest
call to the Terminal API as well additional tender option fields passed in SaleToAcquirerData
:
AllowPartialAuthorisation
- Flags that a partial approval is allowed. As a result, the authorised amount might be lower than the requested amount.AskCharity
- Triggers the terminal to ask if the shopper wants to donate to charity.AskGratuity
- Triggers the terminal to ask if the shopper wants to tip.BypassPin
- Bypasses PIN entry where the shopper does not know the PIN for the card and the Merchant either knows they are the legitimate cardholder or wants to give them the benefit of the doubt.ForcedDecline
- Forces a decline of the transaction, for example, if fraud is suspected.ReceiptHandler
- Specifies that the POS handles and prints receipts. If omitted, it is required that the PED prints the receipt. If there is no printer unit, the transaction will fail.For more information on the fields required for receipts, see Receipt requirements for card schemes.
MOTO
- Triggers MOTO transactions on the payment terminal from the Cash register. MOTO transactions are card-not-present transactions, where the payment details are presented to a merchant by a shopper by means of mail (not email), fax, or telephone.SkipAIDPriority
- Skip a card's application identifier (AID) priority. This allows a shopper to select their preferred card application.
{ "SaleToPOIRequest": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "Payment", "MessageType": "Request", "ServiceID": "0110123015", "SaleID": "POSSystemID12345", "POIID": "MX925-260193322" }, "PaymentRequest": { "SaleData": { "SaleTransactionID": { "TransactionID": "5748", "TimeStamp": "2018-01-10T11:30:15+00:00" }, "SaleToAcquirerData": "tenderOption=AskGratuity" }, "PaymentTransaction": { "AmountsReq": { "Currency": "EUR", "RequestedAmount": 10.99 } } } } }
Response
For a list of Payment Response fields, see PaymentResponse fields.
An authorisation is attempted and you receive a response with the following fields:
AskGratuity response
"AmountsResp": { "AuthorizedAmount": 12.24, "Currency": "EUR", "TipAmount": 1.25 }
Keyed ForceEntryMode response
"PaymentInstrumentData": { "CardData": { "CardCountryCode": "528", "EntryMode": [ "Keyed" ], "MaskedPan": "510029 **** 2909", "PaymentBrand": "mccredit", "SensitiveCardData": { "ExpiryDate": "1020" } }, "PaymentInstrumentType": "Card" },
If you receive an error, you may need to troubleshoot accordingly. For more information, see Error Scenarios.
Warnings are triggered when non-fatal errors occur. These are returned for your information in the response.