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 the Terminal API Overview .

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, use our Error Scenarios page to troubleshoot the issue.

Warnings are triggered when non-fatal errors occur and are returned in the response.