Pass tender options using the Terminal API

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

The URL used to send Terminal API messages depends on your type of implementation. For more information on the architectures available, see the Terminal API Overview .

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.

PaymentRequest - Transaction Conditions

{
  "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.

PaymentRequest - Tender Options

{
  "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.