Search

Are you looking for test card numbers?

Would you like to contact support?

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 in a PaymentRequest, for example a shopper reference, or email. In the Terminal API, this is passed in a SaleToAcquirerData field, and can include data to create recurring contracts.

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.

{
   "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=YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j&recurringContract=RECURRING",
            "TokenRequestedType":"Customer",
            "SaleTransactionID":{
               "TransactionID":"8377",
               "TimeStamp":"2017-11-13T15:24:52+00:00"
            }
         }
      }
   }
}

You can pass additional data in form-encoded key-value pairs in the SaleToAcquirerData field.

Alternatively, you can convert it to Base64 encoded JSON, which will provide you with a string like:

eyJzaG9wcGVyRW1haWwiOiJob2xhQGdtYWlsLmNvbSIsInNob3BwZXJSZWZlcmVuY2UiOiJZT1VSX1VOSVFVRV9TSE9QUEVSX0lEX0lPZlczazlHMlB2WEZ1MmoiLCJyZWN1cnJpbmdDb250cmFjdCI6IlJFQ1VSUklORyJ9Cg==

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:

{  
   "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=YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j&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=filler"
                     }
                  ]
               },
               "DocumentQualifier":"CashierReceipt"
            },
            {
               "OutputContent":{
                  "OutputFormat":"Text",
                  "OutputText":[
                     {
                        "CharacterStyle":"Bold",
                        "EndOfLineFlag":true,
                        "Text":"key=header1&name=Adyen"
                     },
                   [...]
                     {
                        "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.