Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Tender options

Review our tender options (settings that change how a transaction is processed) and things to consider when using them.

Tender options allow you to change how a transaction is processed. 

Use the Adyen Customer Area (CA), or pass tender options created on the PED with a transaction to trigger options to be presented to the shopper. For example, AskGratuity, where the shopper is asked to enter a tip, can be set in createTender or as a configuration option for stand-alone terminals.

Name Description
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. Requires that the shopper indicates the PIN is not known. The staff cancel the existing transaction and initiate a new transaction through the POS. They then ask the shopper to press Enter when prompted for a PIN. Subsequently the shopper will need to provide a signature. The Merchant then needs to check the signature and approve it. As a cardholder is expected to know the PIN for the card issued, verifying of the signature as well as cardholder name with some form of identification is recommended.
DontPrintReceipt Specifies that no receipt should be printed.
EnableMagstripeFallback If ICC cannot be processed, magstripe will be used as the POS entry mode. If magstripe is disabled in your configuration, use this tender option to enable it for a transaction.
ForcedDecline Forces a decline of the transaction, for example, if fraud is suspected.
ForcedOnline Forces online authorisation of the transaction. Should only be used in exceptional cases. The terminal tries to process online by default, and if that is not possible, it checks the configured limits to determine if the transaction can be processed offline.
GetAdditionalData Gathers and makes available additional data, after a card is read. The amount of the transaction can be changed based on additional input from the POS; for example, to offer discounts for loyal customers. Used for Dynamic Currency Conversion and loyalty data. To use DCC, specify the getAdditionalData tender option and contact support for backend configuration.
KeyedEntry Triggers MKE processing. If set to true, this requires the merchant or cardholder to enter the card number manually. Used for damaged cards.
For gift card operations, the tender created prior to redemption must not include a KeyedEntry tender option. If the original tender contains the KeyedEntry tender option, it is not possible to update the tender to a gift card redemption.
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.
NoCTLS Disables contactless/NFC as POS entry mode for the transaction.
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.
SkipAIDPriority Skip a card's application identifier (AID) priority. This allows a shopper to select their preferred card application.

Pass tender options

Tender options are settings that modify how a transaction is processed. Tender options are passed to the Terminal API in a PaymentRequest using the TransactionConditions field or the SaleToAcquirerData field.

It is possible to set default tender options. The terminal will then use these options for every payment. Ask the POS Support Team to configure this for you.

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 POS entry modes in TransactionConditions

Choose the type of POS entry mode, how the Card number (PAN) is propagated to the terminal, by using ForceEntryMode, passed in TransactionConditions.

If ForceEntryMode is not included, the default entry modes are used.

To specify an entry mode, set ForceEntryModeto:

  • Keyed - The terminal will request the shopper manually enter their card details.
  • MagStripe - The terminal will request that the shopper use the card's magnetic stripe.
  • Contactless - The terminal will offer a contactless payment to the shopper.

If Contactless is not included, it 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"
          ]
        }
      }
    }
  }
}
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);
paymentRequest.setSaleData(saleData);

PaymentTransaction paymentTransaction = new PaymentTransaction();
AmountsReq amountsReq = new AmountsReq();
amountsReq.setCurrency("EUR");
amountsReq.setRequestedAmount( BigDecimal.valueOf(10.99) );
paymentTransaction.setAmountsReq(amountsReq);

TransactionConditions transactionConditions = new TransactionConditions();
transactionConditions.getForceEntryMode().add( ForceEntryModeType.KEYED );
paymentTransaction.setTransactionConditions(transactionConditions);
paymentRequest.setPaymentTransaction(paymentTransaction);
saleToPOIRequest.setPaymentRequest(paymentRequest);
terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

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.
  • 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 physical mail, fax, or telephone.
  • SkipAIDPriority - Skip a card's application identifier (AID) priority. This allows a shopper to select their preferred card application.

In the following example, the AskGratuity and ReceiptHandler tender options are passed to the terminal:

{
  "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": 10.99
        }
      }
    }
  }
}
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(10.99) );
paymentTransaction.setAmountsReq(amountsReq);
paymentRequest.setPaymentTransaction(paymentTransaction);
saleToPOIRequest.setPaymentRequest(paymentRequest);
terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

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.