Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

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"
            }
         }
      }
   }
}
String POIID = "YOUR_TERMINAL_ID";
String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
String saleID = "YOUR_CASH_REGISTER_ID";
String transactionID = "YOUR_UNIQUE_TRANSACTION_ID";

SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
MessageHeader messageHeader = new MessageHeader();
messageHeader.setPOIID(POIID);
messageHeader.setMessageClass( MessageClassType.SERVICE );
messageHeader.setMessageType( MessageType.REQUEST );
messageHeader.setProtocolVersion("3.0");
messageHeader.setServiceID(serviceID);
messageHeader.setSaleID(saleID);
messageHeader.setMessageCategory( MessageCategoryType.PAYMENT );
saleToPOIRequest.setMessageHeader(messageHeader);

PaymentRequest paymentRequest = new PaymentRequest();
PaymentTransaction paymentTransaction = new PaymentTransaction();
AmountsReq amountsReq = new AmountsReq();
amountsReq.setRequestedAmount( BigDecimal.valueOf(10.99) );
amountsReq.setCurrency("EUR");
paymentTransaction.setAmountsReq(amountsReq);

TransactionConditions transactionConditions = new TransactionConditions();
paymentTransaction.setTransactionConditions(transactionConditions);
paymentRequest.setPaymentTransaction(paymentTransaction);

SaleData saleData = new SaleData();
saleData.setSaleToAcquirerData("shopperEmail=hola@gmail.com&shopperReference=YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j&recurringContract=RECURRING");
saleData.setTokenRequestedType( TokenRequestedType.CUSTOMER );
TransactionIdentification saleTransactionID = new TransactionIdentification();
saleTransactionID.setTransactionID(transactionID);
saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
saleData.setSaleTransactionID(saleTransactionID);
paymentRequest.setSaleData(saleData);
saleToPOIRequest.setPaymentRequest(paymentRequest);
terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

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.