Search docs

Are you looking for test card numbers?

Would you like to contact support?

Start searching Adyen's documentation...

  Documentation

Pass tender options using the Terminal API

Outlines changing the processing of transactions using 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"
          ]
        }
      }
    }
  }
}

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
        }
      }
    }
  }
}

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.