Pass additional data using the Terminal API

Additional data is passed to the Terminal API using the SaleToAcquirerData field.

 Request

Additional Data is 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.

The fields described below are the basic payment fields you specify when making a PaymentRequest call to the Terminal API as well additional data fields (shopperEmailshopperReferencerecurringContract, and recurringDetailName) passed in SaleToAcquirerData.

For a list of Payment Response 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"
            }
         }
      }
   }
}

Response

For a list of Payment Response 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