Application information identifies how technology partners connect to Adyen for payment processing. Adyen can use application info to analyze and troubleshoot payments more efficiently, and to provide better support.
Who builds the integration
The fields you're required to include depend on who builds the integration between you and Adyen:
- Partner-built: you build your own integration.
- Integrator-built: you outsource building your integration.
- Pre-built: you are the integrator who customizes a pre-built integration.
Application information fields
The field values you must include depend on who builds the integration:
The following table shows an example in which your company, Best Store Commerce, builds a store application and partners with Adyen to process payments. You built and provide the platform. Your platform has a point of sale (POS) application called Best Instore and an ecommerce application called Best Ecom. Include these fields in the applicationInfo object:
| Field | Description | Required | Example |
|---|---|---|---|
externalPlatform.name |
Your company name or the name of your platform. |  |
Best Store Commerce |
externalPlatform.version |
The software version of the platform. | If your platform has versions. | 1.3 |
externalPlatform.integrator |
Your company name. | |
Best Store Commerce |
merchantApplication.name |
The name of the application or product that a merchant uses. | |
Best Instore or Best Ecom |
merchantApplication.version |
The software version of the application. | If your application has versions. | 2.13.05 |
merchantDevice.os |
The operating system of the device that runs the POS application. | If your merchant application is a POS application. | iOS |
merchantDevice.osVersion |
The software version of the operating system. | If your merchant application is a POS application. | 16.3 |
Field value requirements
The values you send in the application info fields can:
- be between up to 40 characters in length.
- start with a number or letter.
- contain letters, digits, dashes, underscores, and spaces.
The formatting of the values must be the same in every request.
For example, if the externalPlatform.name is Best Store Commerce, you can't sometimes specify that value as BestStoreCommerce or BESTSTORECOMMERCE. You must choose one format and stick to it.
Example API requests
See examples for the following types of applications:
Ecommerce application
The following examples shows how to provide application info in the /payments request.
curl https://checkout-test.adyen.com/v70/payments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
"applicationInfo": {
"externalPlatform": {
"name": "Best Store Commerce",
"version": "1.3",
"integrator": "Best Store Commerce"
},
"merchantApplication": {
"name": "Best Ecom",
"version": "2.13.05"
}
}
...
}'# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR_X-API-KEY"
request = {
:applicationInfo => {
:externalPlatform => {
:name => "Best Store Commerce",
:version => "1.3",
:integrator => "Best Store Commerce"
},
:merchantApplication => {
:name => "Best Ecom",
:version => "2.13.05"
}
},
# Add PaymentRequest information here.
}
response = adyen.checkout.payment_methods(request)// Set your X-API-KEY with the API key from the Customer Area.
Client client = new Client("YOUR_X-API-KEY", Environment.TEST, "null");
Checkout checkout = new Checkout(client);
ApplicationInfo applicationInfo = new ApplicationInfo();
ExternalPlatform externalPlatform = new ExternalPlatform();
externalPlatform.setName("Best Store Commerce");
externalPlatform.setVersion("1.3");
externalPlatform.setIntegrator("Best Store Commerce");
applicationInfo.setExternalPlatform(externalPlatform);
CommonField merchantApplication = new CommonField();
merchantApplication.setName("Best Ecom");
merchantApplication.setVersion("2.13.05");
applicationInfo.setMerchantApplication(merchantApplication);
PaymentsRequest paymentsRequest = new PaymentsRequest();
paymentsRequest.setApplicationInfo(applicationInfo);
// Add PaymentRequest information here.
PaymentsResponse paymentsResponse = checkout.payments(paymentsRequest);// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);
$params = array(
"applicationInfo" => array(
"externalPlatform" => array(
"name" => "Best Store Commerce",
"version" => "1.3",
"integrator" => "Best Store Commerce"
),
"merchantApplication" => array(
"name" => "Best Ecom",
"version" => "2.13.05"
)
)
// Add PaymentRequest information here.
);
$result = $service->payments($params);# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'
request = {
'applicationInfo': {
'externalPlatform': {
'name': 'Best Store Commerce',
'version': '1.3',
'integrator': 'Best Store Commerce'
},
'merchantApplication': {
'name': 'Best Ecom',
'version': '2.13.05',
}
},
# Add PaymentRequest information here.
}
response = adyen.checkout.payment_methods(request)// Set your X-API-KEY with the API key from the Customer Area.
var client = new Client("YOUR-X-API-KEY", environment:Adyen.Model.Enum.Environment.Test);
var checkout = new Checkout(client);
var paymentsRequest = new Adyen.Model.Checkout.PaymentRequest();
var externalPlatform = new Adyen.Model.ApplicationInformation.ExternalPlatform("Best Store Commerce", "1.3", "Best Store Commerce");
var merchantApplication = new Adyen.Model.ApplicationInformation.CommonField("Best Ecom", "2.13.05");
paymentsRequest.ApplicationInfo.ExternalPlatform = externalPlatform;
paymentsRequest.ApplicationInfo.MerchantApplication = merchantApplication;
var paymentResponse = checkout.Payments(paymentsRequest);POS application
To add application info to your payment request, you pass data elements in the SaleToAcquirerData field. There are two ways to do that:
- Option 1: as a JSON object converted to a Base64-encoded string.
- Option 2: as form-encoded key-value pairs (using & as a separator).
This example shows how to add application info 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. For example:
{ "applicationInfo": { "externalPlatform": { "name": "Best Store Commerce", "version": "1.3", "integrator": "AAA Systems" }, "merchantApplication": { "name": "Best Instore", "version": "1.23.5" }, "merchantDevice": { "os": "iOS", "osVersion": "16.3" } } } -
Encode the JSON object to Base64.
ewogICAgImFwcGxpY2F0aW9uSW5mbyI6ewogICAgICAgICJleHRlcm5hbFBsYXRmb3JtIjp7CiAgICAgICAgICAgICJuYW1lIjoiQmVzdCBTdG9yZSBDb21tZXJjZSIsCiAgICAgICAgICAgICJ2ZXJzaW9uIjoiMS4zIiwKICAgICAgICAgICAgImludGVncmF0b3IiOiJBQUEgU3lzdGVtcyIKICAgICAgICB9LAogICAgICAgICJtZXJjaGFudEFwcGxpY2F0aW9uIjp7CiAgICAgICAgICAgICJuYW1lIjoiQmVzdCBJbnN0b3JlIiwKICAgICAgICAgICAgInZlcnNpb24iOiIyLjEzLjA1IgogICAgICAgIH0sCiAgICAgICAgIm1lcmNoYW50RGV2aWNlIjp7CiAgICAgICAgICAgICJvcyI6ImlPUyIsCiAgICAgICAgICAgICJvc1ZlcnNpb24iOiIxNi4zIgogICAgICAgIH0KICAgIH0KfQ== -
Make a payment request with:
SaleData.SaletoAcquirerData: The Base64-encoded JSON object.
{ "SaleToPOIRequest": { "PaymentRequest":{ "SaleData":{ "SaleToAcquirerData": "ewogICAgImFwcGxpY2F0aW9uSW5mbyI6ewogICAgICAgICJleHRlcm5hbFBsYXRmb3JtIjp7CiAgICAgICAgICAgICJuYW1lIjoiQmVzdCBTdG9yZSBDb21tZXJjZSIsCiAgICAgICAgICAgICJ2ZXJzaW9uIjoiMS4zIiwKICAgICAgICAgICAgImludGVncmF0b3IiOiJBQUEgU3lzdGVtcyIKICAgICAgICB9LAogICAgICAgICJtZXJjaGFudEFwcGxpY2F0aW9uIjp7CiAgICAgICAgICAgICJuYW1lIjoiQmVzdCBJbnN0b3JlIiwKICAgICAgICAgICAgInZlcnNpb24iOiIyLjEzLjA1IgogICAgICAgIH0sCiAgICAgICAgIm1lcmNoYW50RGV2aWNlIjp7CiAgICAgICAgICAgICJvcyI6ImlPUyIsCiAgICAgICAgICAgICJvc1ZlcnNpb24iOiIxNi4zIgogICAgICAgIH0KICAgIH0KfQ==", "SaleTransactionID": { "TransactionID": "27909", "TimeStamp": "2020-04-16T11:53: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("ewogICAgImFwcGxpY2F0aW9uSW5mbyI6ewogICAgICAgICJleHRlcm5hbFBsYXRmb3JtIjp7CiAgICAgICAgICAgICJuYW1lIjoiQmVzdCBTdG9yZSBDb21tZXJjZSIsCiAgICAgICAgICAgICJ2ZXJzaW9uIjoiMS4zIiwKICAgICAgICAgICAgImludGVncmF0b3IiOiJBQUEgU3lzdGVtcyIKICAgICAgICB9LAogICAgICAgICJtZXJjaGFudEFwcGxpY2F0aW9uIjp7CiAgICAgICAgICAgICJuYW1lIjoiQmVzdCBJbnN0b3JlIiwKICAgICAgICAgICAgInZlcnNpb24iOiIyLjEzLjA1IgogICAgICAgIH0sCiAgICAgICAgIm1lcmNoYW50RGV2aWNlIjp7CiAgICAgICAgICAgICJvcyI6ImlPUyIsCiAgICAgICAgICAgICJvc1ZlcnNpb24iOiIxNi4zIgogICAgICAgIH0KICAgIH0KfQ=="); 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 the
AdditionalResponsein the same format as theSaleToAcquirerData, a Base64-encoded JSON object.{ "SaleToPOIResponse": { "PaymentResponse": { "POIData": {...}, "SaleData": {...}, "PaymentReceipt": [...], "PaymentResult": { "OnlineFlag": true, "PaymentAcquirerData": {...}, "PaymentInstrumentData": { "CardData": {...} }, "PaymentInstrumentType": "Card" }, "AmountsResp": { "AuthorizedAmount": 10.99, "Currency": "EUR" }, "CustomerLanguage": "nl" }, "Response": { "Result": "Success", "AdditionalResponse": "eyAidGlkIjogIjQ2NDAzMTYxIiwgIkFJRCI6ICJBMDAwMDAwMDA0MTAxMDAxIiwgInRyYW5zYWN0aW9uVHlwZSI6ICJHT09EU19TRVJWSUNFUyIsICJ0cmFuc2FjdGlvbkxhbmd1YWdlIjogIm5sIiwgImJhY2tlbmRHaWZ0Y2FyZEluZGljYXRvciI6ICJmYWxzZSIsICJwb3NhZGRpdGlvbmFsYW1vdW50cy5vcmlnaW5hbEFtb3VudFZhbHVlIjogIjEwOTkiLCAiZXhwaXJ5WWVhciI6ICIyMDI4IiwgImFjcXVpcmVyQWNjb3VudENvZGUiOiAiVGVzdFBtbUFjcXVpcmVyQWNjb3VudCIsICJhbGlhcyI6ICJNNDY5NTA5NTk0ODU5ODAyIiwgInBvc0Ftb3VudEdyYXR1aXR5VmFsdWUiOiAiMCIsICJnaWZ0Y2FyZEluZGljYXRvciI6ICJmYWxzZSIsICJhdXRob3Jpc2VkQW1vdW50VmFsdWUiOiAiMTA5OSIsICJwc3BSZWZlcmVuY2UiOiAiODUzNTg3MDMwODM0OTE3OCIsICJwYXltZW50TWV0aG9kVmFyaWFudCI6ICJtYyIsICJyZWZ1c2FsUmVhc29uUmF3IjogIkFQUFJPVkVEIiwgImF1dGhvcmlzYXRpb25NaWQiOiAiMTAwMCIsICJhcHBsaWNhdGlvblByZWZlcnJlZE5hbWUiOiAibWMgbmwiLCAiYWNxdWlyZXJDb2RlIjogIlRlc3RQbW1BY3F1aXJlciIsICJzdG9yZSI6ICJTdG9yZU9uZSIsICJ0eHRpbWUiOiAiMTE6NTM6NDkiLCAiaXNvODYwMVR4RGF0ZSI6ICIyMDIwLTA0LTE2VDA5OjUzOjQ5LjAwMDAwMDArMDAwMCIsICJjYXJkVHlwZSI6ICJtYyIsICJwb3NPcmlnaW5hbEFtb3VudFZhbHVlIjogIjEwOTkiLCAib2ZmbGluZSI6ICJmYWxzZSIsICJhbGlhc1R5cGUiOiAiRGVmYXVsdCIsICJ0eGRhdGUiOiAiMTYtMDQtMjAyMCIsICJwYXltZW50TWV0aG9kIjogIm1jIiwgImN2Y1Jlc3VsdCI6ICIwIFVua25vd24iLCAiYXV0aG9yaXNlZEFtb3VudEN1cnJlbmN5IjogIkVVUiIsICJzdGFydFllYXIiOiAiMjAxNyIsICJ0YyI6ICJFNEM3RUFEREFDMzgzNEVEIiwgImF2c1Jlc3VsdCI6ICIwIFVua25vd24iLCAiY2FyZElzc3VlTnVtYmVyIjogIjgzIiwgIm1pZCI6ICIxMDAwIiwgIm1lcmNoYW50UmVmZXJlbmNlIjogIjI3OTA5IiwgInRyYW5zYWN0aW9uUmVmZXJlbmNlTnVtYmVyIjogIjg1MzU4NzAzMDgzNDkxNzgiLCAiZXhwaXJ5TW9udGgiOiAiMDIiLCAiY2FyZFN1bW1hcnkiOiAiOTk5OSIsICJwb3NhZGRpdGlvbmFsYW1vdW50cy5vcmlnaW5hbEFtb3VudEN1cnJlbmN5IjogIkVVUiIsICJwb3NBdXRoQW1vdW50Q3VycmVuY3kiOiAiRVVSIiwgImNhcmRIb2xkZXJWZXJpZmljYXRpb25NZXRob2RSZXN1bHRzIjogIjFGMDMwMiIsICJhdXRoQ29kZSI6ICIxMjM0NTYiLCAiY2FyZElzc3VlckNvdW50cnlJZCI6ICIwNTYiLCAiYWRqdXN0QXV0aG9yaXNhdGlvbkRhdGEiOiAiQlFBQkFRQVdjckx0ZE1qSFRDam1WVzQzY3dWQitOSWN2dU54aGpKTSt1NlA3YXZiUm1ITzY4cnVzZER3eGFYRnhjMzBsQ1YwRnBlcGhlK0VSV3o3NUx1YWJaRVBXYTduYkNqVDNSS2VJTDYxa0VOb1B0VkdRUGtmSlhKOHpNTUZCWEw2cmNzNlFybU5uTjdcL2JXa3NrT0NBNUpTRFBQZ1NocVhIWHhPQ1wvWFJNRGNxNUZtUVFNNUtkZlpiOXVFMXdJOWJ4RHdWQTgxVmcrRm82Z3dKdnMwRUoxK3BzN0FTOHV5eTNpenFUY3E1aFJ5c1pyaEwydVRZNk9udlduMDNKYWdhaTB3Q2hFRmpDamF1cFBBbitPU3hGV1JxbTErQVRCc3hBd2M0Z29ISFRYaFwvYUk3XC9hbVJuMUlLdDlFaUN0bG1LRVRHYkREUXFUZG5ZclBiejdROGsrUGtkMUVPN09tRTdEQ1Y1MjN4TFVKbUs5TnpvQUFGam1yeFhrRkxnajl5V3NsZlVWOXZ3QnlHb2I1UWtHN0JWVGg1U25ONDBpWHUwN2NsRjc5MnR6MXRWMVhIM2szblgxSVkxOVMwMnJTdnlOTDhOblBCUUx2Uk9rMmc0NVFVSHhCQU0rUWxJSVJwN0VYOWhhY0ZrR3RRSnQzaXpuXC9rczB5V3F2VXA0VVcxY2twK1p5RTZoXC9pRmFSOHlMaUVobDNZU1NMNXlHSmpEOE9RMGpLN0ZWbUFcL003emx0Y3lwOFFTQmd4Y2NTUUNRY2FGNDJhZHo4bjU2OVkzdE50NXBYRVFHU1gzWUZXWFUzSE1EOVFXXC9GeFUrYmltaVFjZXZ5WklmY1JNMHNhMU5DTDJ6TyszcEQxcndXQTVCUXMwcTdzTEkxZytNQ3ZvWFRnZ2J4Vyt3T2x4VFlSVFYwSHkyc3hwQ213VDlcL000SGladHRJZndLRmZjS2xIemFpeHdiSmJcL0NVeWhsdHk0QUNINW5PK0xZNFlZVTJJTktwRTBkeGhtU1hVeGpKcUNLUGhKTU0rT0JkXC95ZUdYVEQwTUd6bUlaeURrN1J4QXlwSjlsYktQbTdKY2dPNzZJS0NUQkswcWZEd0dKdz09IiwgInBvc0Ftb3VudENhc2hiYWNrVmFsdWUiOiAiMCIsICJwb3NFbnRyeU1vZGUiOiAiQ0xFU1NfQ0hJUCIsICJzdGFydE1vbnRoIjogIjAxIiwgImZ1bmRpbmdTb3VyY2UiOiAiQ1JFRElUIiwgImlzc3VlckNvdW50cnkiOiAiQkUiLCAiY2FyZFNjaGVtZSI6ICJtYyIsICJjYXJkQmluIjogIjU0MTMzMyIsICJwb3NBdXRoQW1vdW50VmFsdWUiOiAiMTA5OSIgfQ==" } }, "MessageHeader": {...} } } -
Decode the Base64 string in the
AdditionalResponsefield of the payment response.
This contains data resulting from the processing of the payment.
The format of the SaleToAcquirerData, Base64-encoded or key-value pairs, determines the format of the AdditionalResponse that you receive. To always receive the AdditionalResponse in one of those formats, contact our POS Support Team.
Combining application info and other data elements
Apart from application info, you can also add other information in the SaleToAcquirerData field. For example, you can add tender options or metadata.
To combine application info and other data elements, see Add information to a payment.