Pass additional data using the Terminal API

Outlines using the terminal API to pass additional data in a payment request.


Additional data allows you to include extra information about your shoppers in a PaymentRequest, for example a shopper reference, or email. In the Terminal API, this is passed in a SaleToAcquirerData field.

Endpoint

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

Request

For a list of PaymentRequest fields, see PaymentRequest fields.

PaymentRequest
{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "POIID":"MX925-286240330",
         "MessageClass":"Service",
         "MessageType":"Request",
         "ProtocolVersion":"3.0",
         "ServiceID":"1113162452",
         "SaleID":"POSSystemID12345",
         "MessageCategory":"Payment"
      },
      "PaymentRequest":{
         "PaymentTransaction":{
            "AmountsReq":{
               "RequestedAmount":10.99,
               "Currency":"EUR"
            },
            "TransactionConditions":{

            }
         },
         "SaleData":{
            "SaleToAcquirerData":"shopperEmail=hola@gmail.com&shopperReference=fakeRef&recurringContract=RECURRING",
            "TokenRequestedType":"Customer",
            "SaleTransactionID":{
               "TransactionID":"8377",
               "TimeStamp":"2017-11-13T15:24:52+00:00"
            }
         }
      }
   }
}

Additional Data is passed in form-encoded key-value pairs in the SaleToAcquirerData field. This can include data to create recurring contracts.

Response

For a list of PaymentResponse fields, see PaymentResponse fields.

An authorisation is attempted and you receive a response with the following fields, including an AdditionalResponse:

PaymentResponse
{  
   "SaleToPOIResponse":{  
      "PaymentResponse":{  
         "Response":{  
            "AdditionalResponse":"applicationLabel=MCDCCFR&cardHolderVerificationMethodResults=440002&AID=A000000004101002&applicationPreferredName=mc%20f&tid=12000000&merchantReference=CardRemoval-AskDcc&tc=F2BCABD61478C117&txdate=10-11-2017&paymentMethod=mc&transactionReferenceNumber=8515103155990306&shopperReference=1231&transactionType=GOODS_SERVICES&cardType=mc&offline=false&cardScheme=mc&mid=51&txtime=13%3a06%3a16&shopperEmail=swag%40ill.com&cardHolderName=TC04_MC_Approved_DCC",
            "Result":"Success"
         },
         "PaymentResult":{  
            "PaymentAcquirerData":{  
               "AcquirerTransactionID":{  
                  "TransactionID":"8515103155990306",
                  "TimeStamp":"2017-11-10T12:06:16.000Z"
               },
               "MerchantID":"TestMerchantPOSRobot02",
               "AcquirerPOIID":"MX925-261078152"
            },
            "PaymentInstrumentData":{  
               "CardData":{  
                  "CardCountryCode":"840",
                  "EntryMode":[  
                     "ICC"
                  ],
                  "MaskedPan":"541333 **** 9990",
                  "PaymentBrand":"mc",
                  "SensitiveCardData":{  
                     "CardSeqNumb":"53",
                     "ExpiryDate":"0228"
                  }
               },
               "PaymentInstrumentType":"Card"
            },
            "AmountsResp":{  
               "AuthorizedAmount":300,
               "Currency":"EUR"
            }
         },
         "PaymentReceipt":[
            {
               "OutputContent":{
                  "OutputFormat":"Text",
                  "OutputText":[
                     {
                        "CharacterStyle":"Bold",
                        "EndOfLineFlag":true,
                        "Text":"key=header1&name=Adyen"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=header2&name=www.adyen.com"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "CharacterStyle":"Bold",
                        "EndOfLineFlag":true,
                        "Text":"key=merchantTitle&name=MERCHANT%20COPY"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=txdate&name=txdate&value=07%2f02%2f18"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=txtime&name=txtime&value=11%3a11%3a01"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=pan&name=PAN&value=%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a9999"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=panSeq&name=PANSeq&value=53"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=preferredName&name=prefName&value=mc%20nl"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=cardType&name=cardtype&value=MCNL"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=paymentMethod&name=paymentMethod"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=paymentMethodVariant&name=paymentMethodVariant"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=posEntryMode&name=posEntryMode&value=ICC"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=cvmRes&name=cvmRes&value=SIGNATURE%20VERIFIED"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=aid&name=aid&value=A000000004101001"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=mid&name=mid&value=1009"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=tid&name=tid&value=MX925-289173817"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=ptid&name=ptid&value=12000000"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=authCode&name=authCode&value=123456"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=atc&name=ATC&value=11007"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=buyerId&name=Buyer%20ID"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=walletOperationType&name=Operation%20Type"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=walletTransactionReference&name=Transaction%20Id"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=walletDccAmount&name=DCC%20Amount"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=walletDccRate&name=DCC%20Rate"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=txRef&name=txRef&value=oLkO001517998261000"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=mref&name=reference&value=27908"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=txtype&name=txType&value=GOODS_SERVICES"
                     },
                     {
                        "CharacterStyle":"Bold",
                        "EndOfLineFlag":true,
                        "Text":"key=totalAmount&name=Total&value=%e2%82%ac%c2%a010.99%20%20"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "CharacterStyle":"Bold",
                        "EndOfLineFlag":true,
                        "Text":"key=approved&name=APPROVED"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     }
                  ]
               },
               "DocumentQualifier":"CashierReceipt"
            },
            {
               "OutputContent":{
                  "OutputFormat":"Text",
                  "OutputText":[
                     {
                        "CharacterStyle":"Bold",
                        "EndOfLineFlag":true,
                        "Text":"key=header1&name=Adyen"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=header2&name=www.adyen.com"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "CharacterStyle":"Bold",
                        "EndOfLineFlag":true,
                        "Text":"key=cardholderHeader&name=CARDHOLDER%20COPY"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=txdate&name=txdate&value=07%2f02%2f18"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=txtime&name=txtime&value=11%3a11%3a01"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=pan&name=PAN&value=%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a9999"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=panSeq&name=PANSeq&value=53"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=preferredName&name=prefName&value=mc%20nl"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=cardType&name=cardtype&value=MCNL"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=paymentMethod&name=paymentMethod"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=paymentMethodVariant&name=paymentMethodVariant"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=posEntryMode&name=posEntryMode&value=ICC"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=cvmRes&name=cvmRes&value=HANDTEKENING%20GECONTROLEERD"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=aid&name=aid&value=A000000004101001"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=mid&name=mid&value=%2a%2a%2a%2a%2a%2a%2a%2a%2a1009"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=tid&name=tid&value=MX925-289173817"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=ptid&name=ptid&value=12000000"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=authCode&name=authCode&value=123456"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=atc&name=ATC&value=11007"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=buyerId&name=Koper-ID"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=walletOperationType&name=Type%20bewerking"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=walletTransactionReference&name=Transactie-ID"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=walletDccAmount&name=DCC-bedrag"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=walletDccRate&name=DCC-tarief"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=txRef&name=txRef&value=oLkO001517998261000"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=mref&name=reference&value=27908"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=txtype&name=txType&value=GOODS_SERVICES"
                     },
                     {
                        "CharacterStyle":"Bold",
                        "EndOfLineFlag":true,
                        "Text":"key=totalAmount&name=Total&value=%e2%82%ac%c2%a010.99%20%20"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "CharacterStyle":"Bold",
                        "EndOfLineFlag":true,
                        "Text":"key=approved&name=APPROVED"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=retain&name=Retain%20for%20your%20records"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=filler"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=thanks&name=Thank%20you"
                     }
                  ]
               },
               "DocumentQualifier":"CustomerReceipt"
            }
         ],
         "POIData":{  
            "POITransactionID":{  
               "TransactionID":"oLkO001510315576349.8515103155990306",
               "TimeStamp":"2017-11-10T12:06:16.000Z"
            }
         },
         "SaleData":{  
            "SaleTransactionID":{  
               "TransactionID":"CardRemoval-AskDcc",
               "TimeStamp":"2017-11-10T12:05:58.686Z"
            }
         }
      },
      "MessageHeader":{  
         "SaleID":"POSSystemID12345",
         "ProtocolVersion":"3.0",
         "MessageType":"Response",
         "POIID":"MX925-261078152",
         "ServiceID":"885906155",
         "MessageClass":"Service",
         "MessageCategory":"Payment"
      }
   }
}

If you receive an error, you may need to troubleshoot accordinlgy. For more information, see Error Scenarios.

Warnings are triggered when non-fatal errors occur. These are returned for your information in the response.

Examples of Additional Data

Key Description Example
AcquirerError Any error response returned from the PAL.  
POIError Any error returned by VOS.  

cardAlias

Alias used instead of the card details.  
cardIssueNumber A one to two digit number printed on teh card. Some cards do not have an issue number. 53
cardHolderName The name of the person using the card. TC02_MC_Approved
transactionType The type of financial transaction. GOODS_SERVICES
paymentMethod

The payment method used in the transaction.

mc
paymentMethodVariant: Rreturns the type of payment method  used during a transaction. mccredit
applicationLabel Mnemonic associated with the AID. MCNL
applicationPreferredName Preferred mnemonic associated with the AID  mc nl
AID  Application Identifier, used to address an application in the card. A000000004101001
shopperReference
The shopper's reference for the payment transaction.
123456789
shopperEmail The shopper's email address. my.name@email.com
recurringDetailReference

Reference for a recurring contract. Only available in case of a CardAcquisition where Entrymode=File and shopper reference was passed in the SaleToAcquirerData.

2713134957760046
appinfo.integrator

The name of the integrator company, defined for logging reasons.

This value should be the name of the company deploying cash register or Point-of-Sale solution, for example,  Retail Consultancy Corp.

Acme Corp POS / 1.2.1 / Acme Adyen connector / 0.1 
appinfo.appname

The Integrator/Merchant App ID.

Format this value like so: Cash register company and product /  Cash register product version / Adyen integration name / Adyen integration version. For example,  Acme Corp POS / 1.2.1 / Acme Adyen connector / 0.1 

Retail Consultancy Corp.