In a basic Terminal API payment request you only need to specify the amount, currency, ID, and timestamp of the transaction. But maybe you want to add information that you want us to apply to your request, or save on the Adyen payments platform. The SaleToAcquirerData
field allows you to do that. In this field you can add all kinds of data elements:
- Application info that we can use for troubleshooting purposes.
- Data to enable shopper recognition and tokenization.
- Tender options to influence how the transaction is processed.
- Additional data for common use cases. For example, for split payments, pre-authorisation, or hospitality.
Refer to the sample collection of SaleToAcquirerData to see what these data elements look like. Below we describe them in a bit more detail, and we explain how to add a combination of data elements to your payment request.
Application info
Application info consists of data elements that identify the software that you use for making payment requests to the Adyen payments platform. When you include application info in your payment requests, we can analyze and troubleshoot payments more efficiently, and provide a better support experience.
For more information refer to Pass application information.
Data to enable shopper recognition and tokenization
Based on shopper identifiers that you receive in your payment response, you can link the payment to a shopper. This enables you to personalize the shopping experience or make recurring payments using a token instead of real card details. But first you need to create those shopper identifiers and store them on the Adyen payments platform. To do so, you include data elements like shopperEmail
, shopperReference
, and recurringContract
in the SaleToAcquirerData
field of your initial payment request.
For more information refer to Shopper recognition and tokenization.
Tender options
By adding one or more tender options to a payment request, you influence how that transaction is processed. For example, you can pass the AskGratuity
tender option to show tipping options on the payment terminal.
For more information refer to Pass tender options.
Additional data
There are many additional data elements that you can add to your payment requests. The list is long and growing, so we can't mention all of them here. See for example the Additional data in our API Explorer. Many of these elements also apply to in-store payments.
Adding data elements to your request
There are two ways to pass data elements in the SaleToAcquirerData
field of your payment request:
- Option 1: As a JSON object converted to a Base64-encoded string.
- Option 2: As form-encoded key-value pairs (using & as a separator).
Refer to the sample collection of SaleToAcquirerData to see what these formats look like.
The format of the SaleToAcquirerData
determines the format of the AdditionalResponse
that you receive.
Receiving the additional response
The AdditionalResponse
in your payment response returns information resulting from the processing of your payment request. It also echoes some of the information you added to your payment request, so you can use this in your business logic.
The additional response can contain many data fields, but you may not need them all. To select the data that you want:
- In your Customer Area, go to Account > API URLs
- On the Additional data settings tab select the options for the type of data you want to receive.
The format of the AdditionalResponse
corresponds with the format of the SaleToAcquirerData
in the payment request: A Base64-encoded JSON object, or form-encoded key-value pairs.
If the request doesn't contain any SaleToAcquirerData
, the AdditionalResponse
will be in key-value pairs format.
Option 1: Pass data elements as Base64-encoded JSON
This example shows how to add data elements to your payment request as a JSON object converted to a Base64-encoded string:
-
Create a JSON object with the data elements you want to pass.
In this example, we use a limited set of data:
- All application information.
- Shopper email and shopper reference.
- Two tender options:
ReceiptHandler
to print the receipt on the cash register, andAskGratuity
to ask for a tip.
So the JSON object looks like this:
{ "applicationInfo": { "merchantApplication": { "name": "Acme Adyen Connector", "version": "2.0" }, "externalPlatform": { "integrator": "Retail Consultancy Co.", "name": "Acme Corporate POS", "version": "1.0.2" }, "merchantDevice": { "os": "Windows 10 Pro", "osVersion": "1909", "reference": "CASH_REGISTER_1234" } }, "shopperEmail": "S.Hopper@example.com", "shopperReference": "CUST01_34582", "tenderOption": "ReceiptHandler,AskGratuity" }
-
Encode the JSON object to Base64.
ICAgIHsKICAgICAgICAiYXBwbGljYXRpb25JbmZvIjogewogICAgICAgICAgICAibWVyY2hhbnRBc HBsaWNhdGlvbiI6IHsKICAgICAgICAgICAgICAgICJuYW1lIjogIkFjbWUgQWR5ZW4gQ29ubmVjdG 9yIiwKICAgICAgICAgICAgICAgICJ2ZXJzaW9uIjogIjIuMCIKICAgICAgICAgICAgfSwKICAgICA gICAgICAgImV4dGVybmFsUGxhdGZvcm0iOiB7CiAgICAgICAgICAgICAgICAiaW50ZWdyYXRvciI6 ICJSZXRhaWwgQ29uc3VsdGFuY3kgQ28uIiwKICAgICAgICAgICAgICAgICJuYW1lIjogIkFjbWUgQ 29ycG9yYXRlIFBPUyIsCiAgICAgICAgICAgICAgICAidmVyc2lvbiI6ICIxLjAuMiIKICAgICAgIC AgICAgfSwKICAgICAgICAgICAgIm1lcmNoYW50RGV2aWNlIjogewogICAgICAgICAgICAgICAgIm9 zIjogIldpbmRvd3MgMTAgUHJvIiwKICAgICAgICAgICAgICAgICJvc1ZlcnNpb24iOiAiMTkwOSIs CiAgICAgICAgICAgICAgICAicmVmZXJlbmNlIjogIkNBU0hfUkVHSVNURVJfMTIzNCIKICAgICAgI CAgICAgfQogICAgICAgIH0sCiAgICAgICAgInNob3BwZXJFbWFpbCI6ICJTLkhvcHBlckBnbWFpbC 5jb20iLAogICAgICAgICJzaG9wcGVyUmVmZXJlbmNlIjogIkNVU1QwMV8zNDU4MiIsCiAgICAgICA gInRlbmRlck9wdGlvbiI6ICJSZWNlaXB0SGFuZGxlcixBc2tHcmF0dWl0eSIKICAgIH0=
-
Make a payment request with:
SaleData.SaletoAcquirerData
: The Base64-encoded JSON object.
{ "SaleToPOIRequest": { "PaymentRequest":{ "SaleData":{ "SaleToAcquirerData":"ICAgIHsKICAgICAgICAiYXBwbGljYXRpb25JbmZvIjogewogICAgICAgICAgICAibWVyY2hhbnRBcHBsaWNhdGlvbiI6IHsKICAgICAgICAgICAgICAgICJuYW1lIjogIkFjbWUgQWR5ZW4gQ29ubmVjdG9yIiwKICAgICAgICAgICAgICAgICJ2ZXJzaW9uIjogIjIuMCIKICAgICAgICAgICAgfSwKICAgICAgICAgICAgImV4dGVybmFsUGxhdGZvcm0iOiB7CiAgICAgICAgICAgICAgICAiaW50ZWdyYXRvciI6ICJSZXRhaWwgQ29uc3VsdGFuY3kgQ28uIiwKICAgICAgICAgICAgICAgICJuYW1lIjogIkFjbWUgQ29ycG9yYXRlIFBPUyIsCiAgICAgICAgICAgICAgICAidmVyc2lvbiI6ICIxLjAuMiIKICAgICAgICAgICAgfSwKICAgICAgICAgICAgIm1lcmNoYW50RGV2aWNlIjogewogICAgICAgICAgICAgICAgIm9zIjogIldpbmRvd3MgMTAgUHJvIiwKICAgICAgICAgICAgICAgICJvc1ZlcnNpb24iOiAiMTkwOSIsCiAgICAgICAgICAgICAgICAicmVmZXJlbmNlIjogIkNBU0hfUkVHSVNURVJfMTIzNCIKICAgICAgICAgICAgfQogICAgICAgIH0sCiAgICAgICAgInNob3BwZXJFbWFpbCI6ICJTLkhvcHBlckBnbWFpbC5jb20iLAogICAgICAgICJzaG9wcGVyUmVmZXJlbmNlIjogIkNVU1QwMV8zNDU4MiIsCiAgICAgICAgInRlbmRlck9wdGlvbiI6ICJSZWNlaXB0SGFuZGxlcixBc2tHcmF0dWl0eSIKICAgIH0=", "SaleTransactionID":{ "TransactionID":"27908", "TimeStamp":"2020-04-08T12:08:52+00:00" } }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"EUR", "RequestedAmount":10.99 } } }, "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Payment", "MessageType":"Request", "ServiceID":"1113162454", "SaleID":"POSSystemID12346", "POIID":"V400m-346403161" } } }
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("ICAgIHsKICAgICAgICAiYXBwbGljYXRpb25JbmZvIjogewogICAgICAgICAgICAibWVyY2hhbnRBcHBsaWNhdGlvbiI6IHsKICAgICAgICAgICAgICAgICJuYW1lIjogIkFjbWUgQWR5ZW4gQ29ubmVjdG9yIiwKICAgICAgICAgICAgICAgICJ2ZXJzaW9uIjogIjIuMCIKICAgICAgICAgICAgfSwKICAgICAgICAgICAgImV4dGVybmFsUGxhdGZvcm0iOiB7CiAgICAgICAgICAgICAgICAiaW50ZWdyYXRvciI6ICJSZXRhaWwgQ29uc3VsdGFuY3kgQ28uIiwKICAgICAgICAgICAgICAgICJuYW1lIjogIkFjbWUgQ29ycG9yYXRlIFBPUyIsCiAgICAgICAgICAgICAgICAidmVyc2lvbiI6ICIxLjAuMiIKICAgICAgICAgICAgfSwKICAgICAgICAgICAgIm1lcmNoYW50RGV2aWNlIjogewogICAgICAgICAgICAgICAgIm9zIjogIldpbmRvd3MgMTAgUHJvIiwKICAgICAgICAgICAgICAgICJvc1ZlcnNpb24iOiAiMTkwOSIsCiAgICAgICAgICAgICAgICAicmVmZXJlbmNlIjogIkNBU0hfUkVHSVNURVJfMTIzNCIKICAgICAgICAgICAgfQogICAgICAgIH0sCiAgICAgICAgInNob3BwZXJFbWFpbCI6ICJTLkhvcHBlckBnbWFpbC5jb20iLAogICAgICAgICJzaG9wcGVyUmVmZXJlbmNlIjogIkNVU1QwMV8zNDU4MiIsCiAgICAgICAgInRlbmRlck9wdGlvbiI6ICJSZWNlaXB0SGFuZGxlcixBc2tHcmF0dWl0eSIKICAgIH0="); 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);
Note that the payment response has an
AdditionalResponse
in the same format as theSaleToAcquirerData
field: A Base64-encoded string.{ "SaleToPOIResponse": { "PaymentResponse": { "POIData": {...}, "SaleData": { "SaleTransactionID": { "TimeStamp": "2020-04-08T12:08:52.000Z", "TransactionID": "27908" } }, "PaymentReceipt": [...], "PaymentResult": { "AuthenticationMethod": [ "OfflinePIN" ], "OnlineFlag": true, "PaymentAcquirerData": {...}, }, "PaymentInstrumentData": { "CardData": { "EntryMode": [ "ICC" ], "PaymentBrand": "mc", "MaskedPan": "541333 **** 9990", "CardCountryCode": "840", "SensitiveCardData": { "CardSeqNumb": "53", "ExpiryDate": "0228" } }, "PaymentInstrumentType": "Card" }, "AmountsResp": { "TipAmount": 1, "AuthorizedAmount": 11.99, "Currency": "EUR" }, "CustomerLanguage": "fr" }, "Response": { "Result": "Success", "AdditionalResponse": "eyAidGlkIjogIjQ2NDAzMTYxIiwgIkFJRCI6ICJBMDAwMDAwMDA0MTAxMDAyIiwgInRyYW5zYWN0aW9uVHlwZSI6ICJHT09EU19TRVJWSUNFUyIsICJ0cmFuc2FjdGlvbkxhbmd1YWdlIjogImZyIiwgImJhY2tlbmRHaWZ0Y2FyZEluZGljYXRvciI6ICJmYWxzZSIsICJwb3NhZGRpdGlvbmFsYW1vdW50cy5vcmlnaW5hbEFtb3VudFZhbHVlIjogIjEwOTkiLCAiZXhwaXJ5WWVhciI6ICIyMDI4IiwgImFjcXVpcmVyQWNjb3VudENvZGUiOiAiVGVzdFBtbUFjcXVpcmVyQWNjb3VudCIsICJhbGlhcyI6ICJBMzczMTc2NzI0MDIyOTQxIiwgInBvc0Ftb3VudEdyYXR1aXR5VmFsdWUiOiAiMTAwIiwgImdyYXR1aXR5QW1vdW50IjogIjEwMCIsICJnaWZ0Y2FyZEluZGljYXRvciI6ICJmYWxzZSIsICJhdXRob3Jpc2VkQW1vdW50VmFsdWUiOiAiMTE5OSIsICJwc3BSZWZlcmVuY2UiOiAiODUyNTg2MzQwNTM2NzI1MiIsICJjYXJkSG9sZGVyTmFtZSI6ICJUQzA0X01DX0FwcHJvdmVkX0RDQyIsICJwYXltZW50TWV0aG9kVmFyaWFudCI6ICJtYyIsICJyZWZ1c2FsUmVhc29uUmF3IjogIkFQUFJPVkVEIiwgImF1dGhvcmlzYXRpb25NaWQiOiAiMTAwMCIsICJhcHBsaWNhdGlvblByZWZlcnJlZE5hbWUiOiAibWMgZiIsICJhY3F1aXJlckNvZGUiOiAiVGVzdFBtbUFjcXVpcmVyIiwgInN0b3JlIjogIlN0b3JlT25lIiwgInR4dGltZSI6ICIxMjowODozNiIsICJpc284NjAxVHhEYXRlIjogIjIwMjAtMDQtMDhUMTA6MDg6MzYuMDAwMDAwMCswMDAwIiwgImNhcmRUeXBlIjogIm1jIiwgInBvc09yaWdpbmFsQW1vdW50VmFsdWUiOiAiMTA5OSIsICJvZmZsaW5lIjogImZhbHNlIiwgImFsaWFzVHlwZSI6ICJEZWZhdWx0IiwgInJlY3VycmluZy5zaG9wcGVyUmVmZXJlbmNlIjogIkNVU1QwMV8zNDU4MiIsICJ0eGRhdGUiOiAiMDgtMDQtMjAyMCIsICJwYXltZW50TWV0aG9kIjogIm1jIiwgImN2Y1Jlc3VsdCI6ICIwIFVua25vd24iLCAiYXV0aG9yaXNlZEFtb3VudEN1cnJlbmN5IjogIkVVUiIsICJzaG9wcGVyUmVmZXJlbmNlIjogIkNVU1QwMV8zNDU4MiIsICJzaG9wcGVyRW1haWwiOiAiUy5Ib3BwZXJAZ21haWwuY29tIiwgInRjIjogIkM3QURFNDdDRUQyRTE4MEQiLCAiYXZzUmVzdWx0IjogIjAgVW5rbm93biIsICJjYXJkSXNzdWVOdW1iZXIiOiAiNTMiLCAibWlkIjogIjEwMDAiLCAibWVyY2hhbnRSZWZlcmVuY2UiOiAiMjc5MDgiLCAidHJhbnNhY3Rpb25SZWZlcmVuY2VOdW1iZXIiOiAiODUyNTg2MzQwNTM2NzI1MiIsICJhcHBsaWNhdGlvbkxhYmVsIjogIk1DRENDRlIiLCAiZXhwaXJ5TW9udGgiOiAiMDIiLCAiY2FyZFN1bW1hcnkiOiAiOTk5MCIsICJwb3NhZGRpdGlvbmFsYW1vdW50cy5vcmlnaW5hbEFtb3VudEN1cnJlbmN5IjogIkVVUiIsICJwb3NBdXRoQW1vdW50Q3VycmVuY3kiOiAiRVVSIiwgImNhcmRIb2xkZXJWZXJpZmljYXRpb25NZXRob2RSZXN1bHRzIjogIjQ0MDAwMiIsICJhdXRoQ29kZSI6ICIxMjM0NTYiLCAiY2FyZElzc3VlckNvdW50cnlJZCI6ICI4NDAiLCAiYWRqdXN0QXV0aG9yaXNhdGlvbkRhdGEiOiAiQlFBQkFRQjN1OG1zbkVuT0R6REVNTmtMS2FOVzRNdUVNWXhMVWluRnpNM2EwdDUwa2NFaHRcL3lWMmtrdDFoeEtwRVNTZEF2MEgyaDFcL0d3RlplZkNiQ2VDQXRFM1NydlBZbHd0STFVUldlVHpjaTIyWVRoa2NcL0p6VWlQQjBNM2pmK2YwRmx0UEhuQkZkc0pCNnduS2tYTWxtZENaekhUMjA5UVdsNHJnUzErUXEzVDBZdXU4XC9FMmNyT3BnNlZSZkVTV0w4VTR2NWFyQVNZNStwMzlaNDNxanl1SkZXSVBiTUdhTXZHS0JaR1dadG1pOHRyOWFLVXFzWXlKOGpBREZwdVd5aWQzdm8rWEZMOUxzVzBwdmM5TXBoaU9EeXpmemk4YXpMb3NMTlJ1elpCZitCOXlLQnlES2lHcFY2Q1o1OUVDaTBuTkd2TVwvaFladHVodkhVbkFOWXo2bnpFQ0Q4SWJCWFwvNHBHaVlxSlVCV2Q0bjhBQUFhOCtES1FzdGlOSVJKYVNsKzE4R3ZVbllMcHdveUVIc25KVGRZUVBNdEswUklWQzBQWjVSNVJcL1hCOVl3NUxmTDVuN093eGF1OTFsSWl5NURRTFVGTjllVjJRME1tVFJKVGoxanBySFJuRUlWMWhhb1FxV0piZUpWZjRmUmptdVB1SnRnNUhud0pYZXNDXC9ibEM4bGt2Q1o5V0lqc2xpTGkycmxRNkhuT1FqR3lGVm5kVjNhOEFoWnJrdGVKMW44SWs2aWFaZFVqUlVXR1hJVXBUMkYyZnZVWFV5TzRIZFZpbEFMaEpSU3pYK0RNT0syM05wRXhJUnBVWkZqOWRKS2ptWm1JUlR3bVk2Q20yc2NSXC80aHI3alhlRndIWVJzRE9TV2ZFeTJadllscXRZYUZvQWppTHRxMnVqYjVrVzkzdVlyMXpmMkVBSEpxa0hGRkxYMUEwUURPWGJreDBGajZSbDI3SXZZcTcyTW16ZDZ0YkpGWUxjSjczekVrY2ZGaVZTOEpFZ3d2cjBcLyt2ZGNBS05PaHZ0XC90UlBXbmZaTzBzVEQ3ZFI3RXZNNTY3VUR2eFVFaHRjMk1VaFlXbERlaU1qa01oQU5sNFFmMWl4TWRoSG5xdlcwRDhsS3ZsWkZoS0pMSDBSbUtzbVgrb21iQ3A1S2xDYnVjQXdVaVwvVmV0cTNkR3c9PSIsICJwb3NBbW91bnRDYXNoYmFja1ZhbHVlIjogIjAiLCAicG9zRW50cnlNb2RlIjogIklDQyIsICJmdW5kaW5nU291cmNlIjogIkNSRURJVCIsICJpc3N1ZXJDb3VudHJ5IjogIlVTIiwgImNhcmRTY2hlbWUiOiAibWMiLCAiY2FyZEJpbiI6ICI1NDEzMzMiLCAicG9zQXV0aEFtb3VudFZhbHVlIjogIjExOTkiLCAicG9zYWRkaXRpb25hbGFtb3VudHMuZ3JhdHVpdHlBbW91bnQiOiAiMTAwIiB9" } }, "MessageHeader": {...} } }
-
Decode the Base64 string in the
AdditionalResponse
field of the payment response.
Note that this contains:- The
shopperReference
andshopperEmail
passed in the request. - Data resulting from the processing of the payment.
{ "tid": "46403161", "AID": "A000000004101002", "transactionType": "GOODS_SERVICES", "transactionLanguage": "fr", "backendGiftcardIndicator": "false", "posadditionalamounts.originalAmountValue": "1099", "expiryYear": "2028", "acquirerAccountCode": "TestPmmAcquirerAccount", "alias": "A373176724022941", "posAmountGratuityValue": "100", "gratuityAmount": "100", "giftcardIndicator": "false", "authorisedAmountValue": "1199", "pspReference": "8525863405367252", "cardHolderName": "TC04_MC_Approved_DCC", "paymentMethodVariant": "mc", "refusalReasonRaw": "APPROVED", "authorisationMid": "1000", "applicationPreferredName": "mc f", "acquirerCode": "TestPmmAcquirer", "store": "StoreOne", "txtime": "12:08:36", "iso8601TxDate": "2020-04-08T10:08:36.0000000+0000", "cardType": "mc", "posOriginalAmountValue": "1099", "offline": "false", "aliasType": "Default", "recurring.shopperReference": "CUST01_34582", "txdate": "08-04-2020", "paymentMethod": "mc", "cvcResult": "0 Unknown", "authorisedAmountCurrency": "EUR", "shopperReference": "CUST01_34582", "shopperEmail": "S.Hopper@example.com", "tc": "C7ADE47CED2E180D", "avsResult": "0 Unknown", "cardIssueNumber": "53", "mid": "1000", "merchantReference": "27908", "transactionReferenceNumber": "8525863405367252", "applicationLabel": "MCDCCFR", "expiryMonth": "02", "cardSummary": "9990", "posadditionalamounts.originalAmountCurrency": "EUR", "posAuthAmountCurrency": "EUR", "cardHolderVerificationMethodResults": "440002", "authCode": "123456", "cardIssuerCountryId": "840", "adjustAuthorisationData": "BQABAQB3u8msnEnODzDEMNkLKaNW4MuEMYxLUinFzM3a0t50kcEht\/yV2kkt1hxKpESSdAv0H2h1\/GwFZefCbCeCAtE3SrvPYlwtI1URWeTzci22YThkc\/JzUiPB0M3jf+f0FltPHnBFdsJB6wnKkXMlmdCZzHT209QWl4rgS1+Qq3T0Yuu8\/E2crOpg6VRfESWL8U4v5arASY5+p39Z43qjyuJFWIPbMGaMvGKBZGWZtmi8tr9aKUqsYyJ8jADFpuWyid3vo+XFL9LsW0pvc9MphiODyzfzi8azLosLNRuzZBf+B9yKByDKiGpV6CZ59ECi0nNGvM\/hYZtuhvHUnANYz6nzECD8IbBX\/4pGiYqJUBWd4n8AAAa8+DKQstiNIRJaSl+18GvUnYLpwoyEHsnJTdYQPMtK0RIVC0PZ5R5R\/XB9Yw5LfL5n7Owxau91lIiy5DQLUFN9eV2Q0MmTRJTj1jprHRnEIV1haoQqWJbeJVf4fRjmuPuJtg5HnwJXesC\/blC8lkvCZ9WIjsliLi2rlQ6HnOQjGyFVndV3a8AhZrkteJ1n8Ik6iaZdUjRUWGXIUpT2F2fvUXUyO4HdVilALhJRSzX+DMOK23NpExIRpUZFj9dJKjmZmIRTwmY6Cm2scR\/4hr7jXeFwHYRsDOSWfEy2ZvYlqtYaFoAjiLtq2ujb5kW93uYr1zf2EAHJqkHFFLX1A0QDOXbkx0Fj6Rl27IvYq72Mmzd6tbJFYLcJ73zEkcfFiVS8JEgwvr0\/+vdcAKNOhvt\/tRPWnfZO0sTD7dR7EvM567UDvxUEhtc2MUhYWlDeiMjkMhANl4Qf1ixMdhHnqvW0D8lKvlZFhKJLH0RmKsmX+ombCp5KlCbucAwUi\/Vetq3dGw==", "posAmountCashbackValue": "0", "posEntryMode": "ICC", "fundingSource": "CREDIT", "issuerCountry": "US", "cardScheme": "mc", "cardBin": "541333", "posAuthAmountValue": "1199", "posadditionalamounts.gratuityAmount": "100" }
- The
Option 2: Pass data elements as key-value pairs
This example shows how to add data elements to your payment request as form-encoded key-value pairs.
-
Create a string with the data elements you want to pass in key-value pairs, using & as a separator between the pairs.
In this example, we use a limited set of data:
- All application information:
applicationInfo.merchantApplication.name=Acme Adyen Connector
applicationInfo.merchantApplication.version=2.0
applicationInfo.externalPlatform.integrator=Retail Consultancy Co.
applicationInfo.externalPlatform.name=Acme Corporate POS
applicationInfo.externalPlatform.version=1.0.2
applicationInfo.merchantDevice.os=Windows 10 Pro
applicationInfo.merchantDevice.osVersion=1990
applicationInfo.merchantDevice.reference=CASH_REGISTER_1234
- Shopper email and shopper reference:
shopperEmail=S.Hopper@example.com
andshopperReference=CUST01_34582
- Two tender options to print the receipt on the cash register to ask for a tip:
tenderOption=ReceiptHandler,AskGratuity
So the string looks like this :
applicationInfo.merchantApplication.name=Acme Adyen Connector&applicationInfo .merchantApplication.version=2.0&applicationInfo.externalPlatform.integrator= Retail Consultancy Co.&applicationInfo.externalPlatform.name=Acme Corporate P OS&applicationInfo.externalPlatform.version=1.0.2&applicationInfo.merchantDev ice.os=Windows 10 Pro&applicationInfo.merchantDevice.osVersion=1990&applicati onInfo.merchantDevice.reference=CASH_REGISTER_1234&shopperEmail=S.Hopper@gmai l.com&shopperReference=CUST01_34582&tenderOption=ReceiptHandler,AskGratuity
- All application information:
-
Make a payment request with:
SaleData.SaletoAcquirerData
: Your string of form-encoded key-value pairs.
{ "SaleToPOIRequest": { "PaymentRequest":{ "SaleData":{ "SaleToAcquirerData":"applicationInfo.merchantApplication.name=Acme Adyen Connector&applicationInfo.merchantApplication.version=2.0&applicationInfo.externalPlatform.integrator=Retail Consultancy Co.&applicationInfo.externalPlatform.name=Acme Corporate POS&applicationInfo.externalPlatform.version=1.0.2&applicationInfo.merchantDevice.os=Windows 10 Pro&applicationInfo.merchantDevice.osVersion=1990&applicationInfo.merchantDevice.reference=CASH_REGISTER_1234&shopperEmail=S.Hopper@example.com&shopperReference=CUST01_34582&tenderOption=ReceiptHandler,AskGratuity", "SaleTransactionID":{ "TransactionID":"27908", "TimeStamp":"2020-04-08T12:08:52+00:00" } }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"EUR", "RequestedAmount":10.99 } } }, "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Payment", "MessageType":"Request", "ServiceID":"1113162454", "SaleID":"POSSystemID12346", "POIID":"V400m-346403161" } } }
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("applicationInfo.merchantApplication.name=Acme Adyen Connector&applicationInfo.merchantApplication.version=2.0&applicationInfo.externalPlatform.integrator=Retail Consultancy Co.&applicationInfo.externalPlatform.name=Acme Corporate POS&applicationInfo.externalPlatform.version=1.0.2&applicationInfo.merchantDevice.os=Windows 10 Pro&applicationInfo.merchantDevice.osVersion=1990&applicationInfo.merchantDevice.reference=CASH_REGISTER_1234&shopperEmail=S.Hopper@example.com&shopperReference=CUST01_34582&tenderOption=ReceiptHandler,AskGratuity"); 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);
Note that the payment response has an
AdditionalResponse
in the same format as theSaleToAcquirerData
: Form-encoded key-value pairs. This contains:- The
shopperReference
andshopperEmail
passed in the request. - Data resulting from the processing of the payment.
{ "SaleToPOIResponse": { "PaymentResponse": { "POIData": {...}, "SaleData": { "SaleTransactionID": { "TimeStamp": "2020-04-08T13:53:52.000Z", "TransactionID": "27908" } }, "PaymentReceipt": [...], "PaymentResult": { "AuthenticationMethod": [ "OfflinePIN" ], "OnlineFlag": true, "PaymentAcquirerData": {...}, "PaymentInstrumentData": { "CardData": { "EntryMode": [ "ICC" ], "PaymentBrand": "mc", "MaskedPan": "541333 **** 9990", "CardCountryCode": "840", "SensitiveCardData": { "CardSeqNumb": "53", "ExpiryDate": "0228" } }, "PaymentInstrumentType": "Card" }, "AmountsResp": { "TipAmount": 1, "AuthorizedAmount": 11.99, "Currency": "EUR" }, "CustomerLanguage": "fr" }, "Response": { "Result": "Success", "AdditionalResponse": "tid=46403161&AID=A000000004101002&transactionType=GOODS_SERVICES&transactionLanguage=fr&backendGiftcardIndicator=false&posadditionalamounts.originalAmountValue=1099&expiryYear=2028&acquirerAccountCode=TestPmmAcquirerAccount&alias=A373176724022941&posAmountGratuityValue=100&gratuityAmount=100&giftcardIndicator=false&authorisedAmountValue=1199&pspReference=8313147988756810&cardHolderName=TC04_MC_Approved_DCC&paymentMethodVariant=mc&refusalReasonRaw=APPROVED&authorisationMid=1000&applicationPreferredName=mc%20f&acquirerCode=TestPmmAcquirer&store=StoreOne&txtime=13%3a52%3a27&iso8601TxDate=2020-04-08T11%3a52%3a27.0000000%2b0000&cardType=mc&posOriginalAmountValue=1099&offline=false&aliasType=Default&recurring.shopperReference=CUST01_34582&txdate=08-04-2020&paymentMethod=mc&cvcResult=0%20Unknown&authorisedAmountCurrency=EUR&shopperReference=CUST01_34582&shopperEmail=S.Hopper%40gmail.com&tc=90ECC6EA1F69629A&avsResult=0%20Unknown&cardIssueNumber=53&mid=1000&merchantReference=27908&transactionReferenceNumber=8313147988756810&applicationLabel=MCDCCFR&expiryMonth=02&cardSummary=9990&posadditionalamounts.originalAmountCurrency=EUR&posAuthAmountCurrency=EUR&cardHolderVerificationMethodResults=440002&authCode=123456&cardIssuerCountryId=840&adjustAuthorisationData=BQABAQATOyUPVhPdS%2bdIRyTQ1Z9tnEWy2cF0AYPJogitvGLPvBZiRMKTWqfbuHq7kJf2e0gt1In%2bCSIwBTDuwcb1YUzUaci%2b8RUaPeKNYHCnvaEwbblBkgq%2bS40Y3R4aYOP%2bB6za2h9HgJ8WC51xWTZjnKlTKVc6Kn9TCULlS5iS5VbgzVa3w5CYFY09yVsm%2f3y%2bUeEYlV8xz4TQa1mlVlMp%2bxBw6VgT%2fdmMWl1btHJWgqWC%2bTYDdqm03vL1GIKG%2fa1nftBTNnb3eDnJpzVyqIr%2fwRBvYmp8JpH6knr%2fzCmSdFxD716IMxw2bWMhzqC1bvWjwjfg5Rm4IzyX7Rixm2c3T32DEAUd0IcAKUSWzRmoyzVd300AADqJ9wEliinVJcjukAgxc%2bdTs%2bPJuuacHMiIQPx5wr%2fV9ePde6wAfpaIV1r%2baVOjxPS19sprhjSJ8RZ7cMZKSef68imD8wIGVmhrRMzBUvnJFwT8nmMBfbCGOPebYGUkOiXwq8xasZ7HaNu7WUfUKtHzSP6k0VmJICz6X6pkasyBurZHkljxBPCshI1dCNRWUq1clLCtJ21Q8wAPydtUKfwRFgAZ5Hs95BZQ9E8VVu3UonQ9UxxokyFQMVaWsboJgODfIVguj11mF8QVytt5eopjDvh7hVa67Ax6pVbB99VKSoFrmCuWr7tKVo10KuKrGCTR48%2bvJ50vK%2baaLpGe28ofvibv%2fsqDjLOQl6PeVS5LTm5Kl9Qa9D4sbEDx4Yfy%2bahPPLYpVascyE%2b3f4wlZurCh3TYHS5zzmvifChUtiSvSBIpmZ9VZETDsMsRZDG9OBloEJNpClPnIuKodNFhEIIYHcY%2bqLq3DBM3c2ggHTJtlj6DlLi9di6rkB9dLn94noRSUnOF&posAmountCashbackValue=0&posEntryMode=ICC&fundingSource=CREDIT&issuerCountry=US&cardScheme=mc&cardBin=541333&posAuthAmountValue=1199&posadditionalamounts.gratuityAmount=100" } }, "MessageHeader": {...} } }