Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Pass tender options

Use parameters to change how a transaction is processed.

Using our Standalone solution?

With our Standalone solution, Support can configure tender options and transaction conditions for your account.

Tender options are parameters that change how the tender is processed. For example, the tender option AskGratuity triggers the payment terminal to ask the shopper for a tip.

You pass tender options in your Terminal API payment requests, using the SaleToAcquirerData field.

Other ways to change transaction processing

Apart from passing tender options, there are other ways to influence the transaction processing. You can:

  • Pass a transaction condition in your payment request. This forces the payment terminal to accept a specific card entry method for that payment. This is used for Manual Keyed Entry (MKE) payments.
  • Configure default tender options and transaction conditions. The terminal will then use these for every payment. Ask our POS Support Team for help.

List of tender options

These are the tender options that you can pass in the SaleToAcquirerData field:

Name Description
AllowPartialAuthorisation Flags that a partial approval is allowed and it's possible that the authorised amount is 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 when the shopper says they don't know the PIN for the card and you either know they are the legitimate cardholder or want to give them the benefit of the doubt. This is the process:
  1. Your store staff cancels the existing transaction and initiates a new transaction through the cash register.
  2. The shopper presses the green key (CONFIRM) when prompted for a PIN and provides a signature.
  3. Your store staff checks and approves the signature.
Because a cardholder is expected to know the PIN for their card, we recommend verifying the signature as well as the cardholder name with some form of identification.
EnableMagstripeFallback If the card details can't be obtained from the embedded EMV chip, the magnetic swipe reader is used as the card entry method. If magstripe is disabled in your configuration, use this tender option to enable it for a transaction.
ForcedDecline Forces the transaction to be declined, for example, if fraud is suspected.
GetAdditionalData Gathers and passes additional data, after a card is read. The amount of the transaction can be changed based on additional input from the cash register. Used for currency conversion and shopper recognition. To use these features, you need to configure your account.
MOTO Triggers Mail or Telephone Order 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.
NoCTLS Disables contactless/NFC as entry mode for the transaction.
ReceiptHandler Specifies that the cash register handles and prints receipts. If omitted, it is required that the payment terminal prints the receipt. If there is no printer unit, the transaction will fail.
SkipAIDPriority Skip the application identifier (AID) priority that has been set in your Customer Area. This allows a shopper to select their preferred application (payment method).

Specify tender options

To specify the tender options that you want to use (see the list):

  • Make a PaymentRequest that contains a SaletoAcquirerData field with one or more comma-separated values specified in one of the following formats:

    • Option 1: A JSON object {"tenderOption": "option"} converted to a Base64 encoded string.
      For example, you encode {"tenderOption": "AskGratuity,ReceiptHandler"} to Base64, and pass the result:
      "SaleToAcquirerData": "eyJ0ZW5kZXJPcHRpb24iOiAiQXNrR3JhdHVpdHksUmVjZWlwdEhhbmRsZXIifQ=="

    • Option 2: tenderOption=option.
      For example: "SaleToAcquirerData": "tenderOption=AskGratuity,ReceiptHandler"

    The format that you use here, will also be the format of the AdditionalResponse that you'll receive.

    The following example shows how you would pass the AskGratuity and ReceiptHandler tender options to the terminal. The response shows the shopper added a tip.

    {
      "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,ReceiptHandler"
          },
          "PaymentTransaction": {
            "AmountsReq": {
              "Currency": "EUR",
              "RequestedAmount": 155.75
            }
          }
        }
      }
    }
    {
        "SaleToPOIResponse": {
            "PaymentResponse": {
                ...
                "SaleData": {...},
                    "PaymentReceipt": [...],
                    "PaymentResult": {
                        ...
                        "AmountsResp": {
                            "TipAmount": 13.25,
                            "AuthorizedAmount": 155.75,
                            "Currency": "EUR"
                        }
                    },
                    "Response": {...}
                },
            "MessageHeader": {...}
        }
    }
    String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
    String saleID = "YOUR_CASH_REGISTER_ID";
    String POIID = "YOUR_TERMINAL_ID";
    String transactionID = "YOUR_UNIQUE_TRANSACTION_ID";
    
    SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
    MessageHeader messageHeader = new MessageHeader();
    messageHeader.setProtocolVersion("3.0");
    messageHeader.setMessageClass( MessageClassType.SERVICE );
    messageHeader.setMessageCategory( MessageCategoryType.PAYMENT );
    messageHeader.setMessageType( MessageType.REQUEST );
    messageHeader.setServiceID(serviceID);
    messageHeader.setSaleID(saleID);
    messageHeader.setPOIID(POIID);
    saleToPOIRequest.setMessageHeader(messageHeader);
    
    PaymentRequest paymentRequest = new PaymentRequest();
    SaleData saleData = new SaleData();
    TransactionIdentification saleTransactionID = new TransactionIdentification();
    saleTransactionID.setTransactionID(transactionID);
    saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
    saleData.setSaleTransactionID(saleTransactionID);
    saleData.setSaleToAcquirerData("tenderOption=AskGratuity,ReceiptHandler");
    paymentRequest.setSaleData(saleData);
    
    PaymentTransaction paymentTransaction = new PaymentTransaction();
    AmountsReq amountsReq = new AmountsReq();
    amountsReq.setCurrency("EUR");
    amountsReq.setRequestedAmount( BigDecimal.valueOf(155.75) );
    paymentTransaction.setAmountsReq(amountsReq);
    paymentRequest.setPaymentTransaction(paymentTransaction);
    saleToPOIRequest.setPaymentRequest(paymentRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

Combining tender options and other parameters

Apart from tender options, there are other parameters that are also passed in the SaleToAcquirerData field. For example, you can use parameters for shopper recognition or passing application information.

To combine tender options and other parameters, use one of the following methods:

  • Option 1: Create a JSON object, encode this to Base64, and specify the resulting string.

    This is a sample JSON object:

    {
        "tenderOption": "AskGratuity",
        "shopperEmail": "s.hopper@mail.com",
        "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
        "recurringContract": "RECURRING,ONECLICK"
    }

    After converting the JSON object to a Base64-encoded string, this is how you pass it:

    "SaleToAcquirerData": "ewogICJ0ZW5kZXJPcHRpb24iOiAiQXNrR3JhdHVpdHkiLAogICJzaG9wcGVyRW1haWwiOiAicy5ob3BwZXJAbWFpbC5jb20iLAogICJzaG9wcGVyUmVmZXJlbmNlIjogIllPVVJfVU5JUVVFX1NIT1BQRVJfSUQiLAogICJyZWN1cnJpbmdDb250cmFjdCI6ICJSRUNVUlJJTkcsT05FQ0xJQ0siCn0="
  • Option 2: Specify all values in form-encoded key-value pairs (using & as a separator). For example:

    "SaleToAcquirerData": "tenderOption=AskGratuity&shopperEmail=s.hopper@gmai&shopperReference=YOUR_UNIQUE_SHOPPER_ID&recurringContract=ONECLICK,RECURRING"

See also