Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Add information to a payment

Send us extra data elements such as application info, tender options, and additional data.

A basic Terminal API payment request includes 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:

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 pass application info in your payment requests, we are able to analyze and troubleshoot payments more efficiently, and provide a better support experience.

Metadata

Metadata are data elements that you create yourself. When you add metadata to your payment request, they are echoed in the response so that you can connect the transaction to your metadata. For example, to add a shift number and an employee ID to a payment. You are free to create up to 20 metadata fields, where the maximum field name is 20 characters, and the maximum value 80 characters. See the instructions on how to pass metadata and the examples.

To also receive metadata in your settlement reports, contact our POS Support Team.

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 see Shopper recognition.

Tender options

Tender options are parameters that change how the tender is processed. For example, the tender option AskGratuity triggers the payment terminal to ask the shopper for a tip.

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 point-of-sale 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, 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.

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:

  1. In your Customer Area, go to Developers > API URLs.
  2. 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:

  1. 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.
    • Metadata: metadata.employeeNumber=1
    • Shopper email and shopper reference.
    • Two tender options: ReceiptHandler to let the POS app handle printing or sending the receipt, and AskGratuity to ask for a tip.

    So the JSON object looks like this:

    Data elements in JSON format 
    {
    "applicationInfo": {
        "externalPlatform": {
            "name": "NewStore",
            "integrator": "NewStore",
            "version": "1.0"
        },
        "merchantApplication": {
            "name": "NewStore Associate App",
            "version": "1.23.0 (3)"
        },
        "merchantDevice": {
            "os": "iOS",
            "osVersion": "15.5"
        }
    },
    "metadata": {
        "employeeNumber": "1"
    },
    "shopperEmail": "S.Hopper@example.com",
    "shopperReference": "CUST01_34582",
    "tenderOption": "ReceiptHandler,AskGratuity"
}

  2. Encode the JSON object to Base64.

    ewogICAiYXBwbGljYXRpb25JbmZvIjp7CiAgICAgICJleHRlcm5hbFBsYXRmb3JtIjp7CiAgICAgICAgICJuYW1lIjoiTmV3U3RvcmUiLAogICAgICAgICAiaW50ZWdyYXRvciI6Ik5ld1N0b3JlIiwKICAgICAgICAgInZlcnNpb24iOiIxLjAiCiAgICAgIH0sCiAgICAgICJtZXJjaGFudEFwcGxpY2F0aW9uIjp7CiAgICAgICAgICJuYW1lIjoiTmV3U3RvcmUgQXNzb2NpYXRlIEFwcCIsCiAgICAgICAgICJ2ZXJzaW9uIjoiMS4yMy4wICgzKSIKICAgICAgfSwKICAgICAgIm1lcmNoYW50RGV2aWNlIjp7CiAgICAgICAgICJvcyI6ImlPUyIsCiAgICAgICAgICJvc1ZlcnNpb24iOiIxNS41IgogICAgICB9CiAgIH0sCiAgICJtZXRhZGF0YSI6ewogICAgICAiZW1wbG95ZWVOdW1iZXIiOiIxIgogICB9LAogICAic2hvcHBlckVtYWlsIjoiUy5Ib3BwZXJAZXhhbXBsZS5jb20iLAogICAic2hvcHBlclJlZmVyZW5jZSI6IkNVU1QwMV8zNDU4MiIsCiAgICJ0ZW5kZXJPcHRpb24iOiJSZWNlaXB0SGFuZGxlcixBc2tHcmF0dWl0eSIKfQ==

  3. Make a payment request with:

    • SaleData.SaletoAcquirerData: the Base64-encoded JSON object.
    {
    "SaleToPOIRequest": {
        "PaymentRequest":{
            "SaleData":{
                "SaleToAcquirerData": "ewogICAiYXBwbGljYXRpb25JbmZvIjp7CiAgICAgICJleHRlcm5hbFBsYXRmb3JtIjp7CiAgICAgICAgICJuYW1lIjoiTmV3U3RvcmUiLAogICAgICAgICAiaW50ZWdyYXRvciI6Ik5ld1N0b3JlIiwKICAgICAgICAgInZlcnNpb24iOiIxLjAiCiAgICAgIH0sCiAgICAgICJtZXJjaGFudEFwcGxpY2F0aW9uIjp7CiAgICAgICAgICJuYW1lIjoiTmV3U3RvcmUgQXNzb2NpYXRlIEFwcCIsCiAgICAgICAgICJ2ZXJzaW9uIjoiMS4yMy4wICgzKSIKICAgICAgfSwKICAgICAgIm1lcmNoYW50RGV2aWNlIjp7CiAgICAgICAgICJvcyI6ImlPUyIsCiAgICAgICAgICJvc1ZlcnNpb24iOiIxNS41IgogICAgICB9CiAgIH0sCiAgICJtZXRhZGF0YSI6ewogICAgICAiZW1wbG95ZWVOdW1iZXIiOiIxIgogICB9LAogICAic2hvcHBlckVtYWlsIjoiUy5Ib3BwZXJAZXhhbXBsZS5jb20iLAogICAic2hvcHBlclJlZmVyZW5jZSI6IkNVU1QwMV8zNDU4MiIsCiAgICJ0ZW5kZXJPcHRpb24iOiJSZWNlaXB0SGFuZGxlcixBc2tHcmF0dWl0eSIKfQ==",
                "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("ewogICAiYXBwbGljYXRpb25JbmZvIjp7CiAgICAgICJleHRlcm5hbFBsYXRmb3JtIjp7CiAgICAgICAgICJuYW1lIjoiTmV3U3RvcmUiLAogICAgICAgICAiaW50ZWdyYXRvciI6Ik5ld1N0b3JlIiwKICAgICAgICAgInZlcnNpb24iOiIxLjAiCiAgICAgIH0sCiAgICAgICJtZXJjaGFudEFwcGxpY2F0aW9uIjp7CiAgICAgICAgICJuYW1lIjoiTmV3U3RvcmUgQXNzb2NpYXRlIEFwcCIsCiAgICAgICAgICJ2ZXJzaW9uIjoiMS4yMy4wICgzKSIKICAgICAgfSwKICAgICAgIm1lcmNoYW50RGV2aWNlIjp7CiAgICAgICAgICJvcyI6ImlPUyIsCiAgICAgICAgICJvc1ZlcnNpb24iOiIxNS41IgogICAgICB9CiAgIH0sCiAgICJtZXRhZGF0YSI6ewogICAgICAiZW1wbG95ZWVOdW1iZXIiOiIxIgogICB9LAogICAic2hvcHBlckVtYWlsIjoiUy5Ib3BwZXJAZXhhbXBsZS5jb20iLAogICAic2hvcHBlclJlZmVyZW5jZSI6IkNVU1QwMV8zNDU4MiIsCiAgICJ0ZW5kZXJPcHRpb24iOiJSZWNlaXB0SGFuZGxlcixBc2tHcmF0dWl0eSIKfQ==");
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 the SaleToAcquirerData field: a Base64-encoded string.

    Base64 encoded AdditionalResponse 
    {
    "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": "ewogICAgImFkZGl0aW9uYWxEYXRhIjogewogICAgICAgICJBSUQiOiAiQTAwMDAwMDAwNDEwMTAwMSIsCiAgICAgICAgImFjcXVpcmVyQWNjb3VudENvZGUiOiAiVGVzdFBtbUFjcXVpcmVyQWNjb3VudCIsCiAgICAgICAgImFjcXVpcmVyQ29kZSI6ICJUZXN0UG1tQWNxdWlyZXIiLAogICAgICAgICJhZGp1c3RBdXRob3Jpc2F0aW9uRGF0YSI6ICJCUUFCQVFBNWFEUVN4ckFkTTF5bG9kMVwvWGVyekF4bFA1aEcwRjkycUpJSitmT2JBXC9wUUxjOVwvYnhSYjE3MGgyc3B0K1VMSUh2QVdMckpTaVwvdFRqWWNYMjVQZG9WM2k1bGtOeDRsYkhnS0k1V25tMlJcL1RrZHZ6cWlacTllMENjK29mUW82V2tNb2h1UFwvZHJhU0RpVVNcL3dwSEQ1STZCQ204Qlwva1V5aUtHMDNWUHRNcEo0YnRLbm55NEM2SDhCRGNFYWJ6dG9hdlJxVGRNWVJcL0tsa3FKS2ZxaGQxaFZvQnBmbVpKVFZlTVhwUElWaFFHRFZOYmdTQnUwTlA0VWJneHBzSDUzYzI5MXBRRWJoYUNNdlQxSkI3Z2t5MWJEa2Zjb1hWYWJtQ1JxU0ZcL0pFZGRWMmlncWFrNzdJNGY0bUU1eVVHZkdQeWpqTXl0ODBQYVVDa2k3cXlsbERYRU5PaW9nWTJlXC82NGxaRlhpQmlOQTVZQUFFVGxIMTBCQzZjelZFcXU1ZkVTaCtvZ0JXeHNiUzVkYTNZTG5tTTNqWExOYzl3WXg4M2xicWVsSDNQSjk5dkN6SHI1TkU0dVR5M3R1eWRVNUhGSm5RYmxiN0RDSzJNOW9FMTg2VlErcHFMTEw0ak54K0hyS1lQbmVBQm0zVzJWdjV0QmlyQkV4aUFWSXF3eVwvdHB6blFxOW9nbUZxWDlmQUh0Q3ZxYlZkQ0xDUk1oQUNXc2RyOHhWZ3FxeWFvVkpVVFpBSkIxUjhIZXNnTllUSFhEZ0ZMRHI1byt1Z3ZxaFdCNVRSTUpVUFRkczhuMW0rUHJCQStQTE1BbjB2SnpvR1FxSDVKUkMwN2lYdVZBUVBHXC9GYzl1UjhUMWRveXVndFIrY2l3cVE0MktnMHpNS3VObVBWdENiOVY0eHpwaEpBR3FNK2dWXC9BMVlmMDFyMmxVQ2dZdWFrK05IMENYckhRSitCaVdmcVNVZWlSWkg2ZlNpdE9JQmppUzczNjNFdDRKeEVYOUl2bnZkSzE2c3MxYllOVitiQUU4bVRXRDZDa0tpMHduYU1nVzVIWitjUlVHdWhzUmh4TDNYZ1lxN2ZqbFRMdTNsVkJ5bHVCWDNkTlMzODRsZzFFM0lzUUV6ak5XUXgybFFVYWw5V0VUb3dVWFwvRFZcL1BCWHpITVV6Uk93VGVZNzh5RkVoTT0iLAogICAgICAgICJhbGlhcyI6ICJNNDY5NTA5NTk0ODU5ODAyIiwKICAgICAgICAiYWxpYXNUeXBlIjogIkRlZmF1bHQiLAogICAgICAgICJhcHBsaWNhdGlvblByZWZlcnJlZE5hbWUiOiAibWMgZW4gZ2JyIGdicCIsCiAgICAgICAgImF1dGhDb2RlIjogIjEyMzQ1NiIsCiAgICAgICAgImF1dGhvcmlzYXRpb25NaWQiOiAiMTAwMCIsCiAgICAgICAgImF1dGhvcmlzZWRBbW91bnRDdXJyZW5jeSI6ICJFVVIiLAogICAgICAgICJhdXRob3Jpc2VkQW1vdW50VmFsdWUiOiAiMTE5OSIsCiAgICAgICAgImF2c1Jlc3VsdCI6ICIwIFVua25vd24iLAogICAgICAgICJiYWNrZW5kR2lmdGNhcmRJbmRpY2F0b3IiOiAiZmFsc2UiLAogICAgICAgICJiYXR0ZXJ5TGV2ZWwiOiAiNjclIiwKICAgICAgICAiY2FyZEJpbiI6ICI1NDEzMzMiLAogICAgICAgICJjYXJkSG9sZGVyVmVyaWZpY2F0aW9uTWV0aG9kUmVzdWx0cyI6ICIxRjAzMDIiLAogICAgICAgICJjYXJkSXNzdWVOdW1iZXIiOiAiMzMiLAogICAgICAgICJjYXJkSXNzdWVyQ291bnRyeUlkIjogIjgyNiIsCiAgICAgICAgImNhcmRTY2hlbWUiOiAibWMiLAogICAgICAgICJjYXJkU3VtbWFyeSI6ICI5OTk5IiwKICAgICAgICAiY2FyZFR5cGUiOiAibWMiLAogICAgICAgICJjdmNSZXN1bHQiOiAiMCBVbmtub3duIiwKICAgICAgICAiZXhwaXJ5TW9udGgiOiAiMDIiLAogICAgICAgICJleHBpcnlZZWFyIjogIjIwMjgiLAogICAgICAgICJmdW5kaW5nU291cmNlIjogIkNSRURJVCIsCiAgICAgICAgImdpZnRjYXJkSW5kaWNhdG9yIjogImZhbHNlIiwKICAgICAgICAiZ3JhdHVpdHlBbW91bnQiOiAiMTAwIiwKICAgICAgICAiaXNvODYwMVR4RGF0ZSI6ICIyMDIxLTAyLTE2VDA5OjI4OjMxLjAwMDAwMDArMDAwMCIsCiAgICAgICAgImlzc3VlckNvdW50cnkiOiAiR0IiLAogICAgICAgICJtZXJjaGFudFJlZmVyZW5jZSI6ICI5MyIsCiAgICAgICAgIm1ldGFkYXRhLmVtcGxveWVlTnVtYmVyIjogIjEiLAogICAgICAgICJtaWQiOiAiMTAwMCIsCiAgICAgICAgIm9mZmxpbmUiOiAiZmFsc2UiLAogICAgICAgICJwYXltZW50TWV0aG9kIjogIm1jIiwKICAgICAgICAicGF5bWVudE1ldGhvZFZhcmlhbnQiOiAibWMiLAogICAgICAgICJwb3NBbW91bnRDYXNoYmFja1ZhbHVlIjogIjAiLAogICAgICAgICJwb3NBbW91bnRHcmF0dWl0eVZhbHVlIjogIjEwMCIsCiAgICAgICAgInBvc0F1dGhBbW91bnRDdXJyZW5jeSI6ICJFVVIiLAogICAgICAgICJwb3NBdXRoQW1vdW50VmFsdWUiOiAiMTE5OSIsCiAgICAgICAgInBvc0VudHJ5TW9kZSI6ICJDTEVTU19DSElQIiwKICAgICAgICAicG9zT3JpZ2luYWxBbW91bnRWYWx1ZSI6ICIxMDk5IiwKICAgICAgICAicG9zYWRkaXRpb25hbGFtb3VudHMuZ3JhdHVpdHlBbW91bnQiOiAiMTAwIiwKICAgICAgICAicG9zYWRkaXRpb25hbGFtb3VudHMub3JpZ2luYWxBbW91bnRDdXJyZW5jeSI6ICJFVVIiLAogICAgICAgICJwb3NhZGRpdGlvbmFsYW1vdW50cy5vcmlnaW5hbEFtb3VudFZhbHVlIjogIjEwOTkiLAogICAgICAgICJwc3BSZWZlcmVuY2UiOiAiTkM2SFQ5Q1JUNjVaR044MiIsCiAgICAgICAgInJlY3VycmluZy5zaG9wcGVyUmVmZXJlbmNlIjogIkNVU1QwMV8zNDU4MiIsCiAgICAgICAgInJlZnVzYWxSZWFzb25SYXciOiAiQVBQUk9WRUQiLAogICAgICAgICJyZXRyeS5hdHRlbXB0MS5zaG9wcGVySW50ZXJhY3Rpb24iOiAiUE9TIiwKICAgICAgICAic2hvcHBlckVtYWlsIjogIlMuSG9wcGVyQGV4YW1wbGUuY29tIiwKICAgICAgICAic2hvcHBlclJlZmVyZW5jZSI6ICJDVVNUMDFfMzQ1ODIiLAogICAgICAgICJzdGFydE1vbnRoIjogIjAxIiwKICAgICAgICAic3RhcnRZZWFyIjogIjIwMTciLAogICAgICAgICJ0YyI6ICIyRTVGMTk5NDI3MTRGNUZFIiwKICAgICAgICAidGlkIjogIjQ2NDAzMTYxIiwKICAgICAgICAidHJhbnNhY3Rpb25SZWZlcmVuY2VOdW1iZXIiOiAiTkM2SFQ5Q1JUNjVaR044MiIsCiAgICAgICAgInRyYW5zYWN0aW9uVHlwZSI6ICJHT09EU19TRVJWSUNFUyIsCiAgICAgICAgInR4ZGF0ZSI6ICIxNi0wMi0yMDIxIiwKICAgICAgICAidHh0aW1lIjogIjEwOjI4OjMxIgogICAgfSwKICAgICJzdG9yZSI6ICJZT1VSX1NUT1JFIgp9",
            }
        },
        "MessageHeader": {...}
    }
}

  4. Decode the Base64 string in the AdditionalResponse field of the payment response.
    Note that this contains:

    • The shopperReference and shopperEmail passed in the request.
    • Data resulting from the processing of the payment.
    Decoded Base64 AdditionalResponse 
    {
    "additionalData": {
        "AID": "A000000004101001",
        "acquirerAccountCode": "TestPmmAcquirerAccount",
        "acquirerCode": "TestPmmAcquirer",
        "adjustAuthorisationData": "BQABAQA5aDQSxrAdM1ylod1\/XerzAxlP5hG0F92qJIJ+fObA\/pQLc9\/bxRb170h2spt+ULIHvAWLrJSi\/tTjYcX25PdoV3i5lkNx4lbHgKI5Wnm2R\/TkdvzqiZq9e0Cc+ofQo6WkMohuP\/draSDiUS\/wpHD5I6BCm8B\/kUyiKG03VPtMpJ4btKnny4C6H8BDcEabztoavRqTdMYR\/KlkqJKfqhd1hVoBpfmZJTVeMXpPIVhQGDVNbgSBu0NP4UbgxpsH53c291pQEbhaCMvT1JB7gky1bDkfcoXVabmCRqSF\/JEddV2igqak77I4f4mE5yUGfGPyjjMyt80PaUCki7qyllDXENOiogY2e\/64lZFXiBiNA5YAAETlH10BC6czVEqu5fESh+ogBWxsbS5da3YLnmM3jXLNc9wYx83lbqelH3PJ99vCzHr5NE4uTy3tuydU5HFJnQblb7DCK2M9oE186VQ+pqLLL4jNx+HrKYPneABm3W2Vv5tBirBExiAVIqwy\/tpznQq9ogmFqX9fAHtCvqbVdCLCRMhACWsdr8xVgqqyaoVJUTZAJB1R8HesgNYTHXDgFLDr5o+ugvqhWB5TRMJUPTds8n1m+PrBA+PLMAn0vJzoGQqH5JRC07iXuVAQPG\/Fc9uR8T1doyugtR+ciwqQ42Kg0zMKuNmPVtCb9V4xzphJAGqM+gV\/A1Yf01r2lUCgYuak+NH0CXrHQJ+BiWfqSUeiRZH6fSitOIBjiS7363Et4JxEX9IvnvdK16ss1bYNV+bAE8mTWD6CkKi0wnaMgW5HZ+cRUGuhsRhxL3XgYq7fjlTLu3lVByluBX3dNS384lg1E3IsQEzjNWQx2lQUal9WETowUX\/DV\/PBXzHMUzROwTeY78yFEhM=",
        "alias": "M469509594859802",
        "aliasType": "Default",
        "applicationPreferredName": "mc en gbr gbp",
        "authCode": "123456",
        "authorisationMid": "1000",
        "authorisedAmountCurrency": "EUR",
        "authorisedAmountValue": "1199",
        "avsResult": "0 Unknown",
        "backendGiftcardIndicator": "false",
        "batteryLevel": "67%",
        "cardBin": "541333",
        "cardHolderVerificationMethodResults": "1F0302",
        "cardIssueNumber": "33",
        "cardIssuerCountryId": "826",
        "cardScheme": "mc",
        "cardSummary": "9999",
        "cardType": "mc",
        "cvcResult": "0 Unknown",
        "expiryMonth": "02",
        "expiryYear": "2028",
        "fundingSource": "CREDIT",
        "giftcardIndicator": "false",
        "gratuityAmount": "100",
        "iso8601TxDate": "2021-02-16T09:28:31.0000000+0000",
        "issuerCountry": "GB",
        "merchantReference": "93",
        "metadata.employeeNumber": "1",
        "mid": "1000",
        "offline": "false",
        "paymentMethod": "mc",
        "paymentMethodVariant": "mc",
        "posAmountCashbackValue": "0",
        "posAmountGratuityValue": "100",
        "posAuthAmountCurrency": "EUR",
        "posAuthAmountValue": "1199",
        "posEntryMode": "CLESS_CHIP",
        "posOriginalAmountValue": "1099",
        "posadditionalamounts.gratuityAmount": "100",
        "posadditionalamounts.originalAmountCurrency": "EUR",
        "posadditionalamounts.originalAmountValue": "1099",
        "pspReference": "NC6HT9CRT65ZGN82",
        "recurring.shopperReference": "CUST01_34582",
        "refusalReasonRaw": "APPROVED",
        "retry.attempt1.shopperInteraction": "POS",
        "shopperEmail": "S.Hopper@example.com",
        "shopperReference": "CUST01_34582",
        "startMonth": "01",
        "startYear": "2017",
        "tc": "2E5F19942714F5FE",
        "tid": "46403161",
        "transactionReferenceNumber": "NC6HT9CRT65ZGN82",
        "transactionType": "GOODS_SERVICES",
        "txdate": "16-02-2021",
        "txtime": "10:28:31"
    },
    "store": "YOUR_STORE"
}

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.

  1. 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.externalPlatform.name=NewStore
      applicationInfo.externalPlatform.integrator=NewStore
      applicationInfo.externalPlatform.version=1.0
      applicationInfo.merchantApplication.name=NewStore Associate App
      applicationInfo.merchantApplication.version=1.23.0 (3)
      applicationInfo.merchantDevice.os=iOS
      applicationInfo.merchantDevice.osVersion=15.5
    • Metadata: metadata.employeeNumber=1
    • Shopper email and shopper reference:
      shopperEmail=S.Hopper@example.com and shopperReference=CUST01_34582
    • Two tender options to let the POS app handle printing or sending the receipt, and to ask for a tip:
      tenderOption=ReceiptHandler,AskGratuity

    So the string looks like this:

    applicationInfo.externalPlatform.name=NewStore&applicationInfo.externalPlatform.integrator=NewStore&applicationInfo.externalPlatform.version=1.0&applicationInfo.merchantApplication.name=NewStore Associate App&applicationInfo.merchantApplication.version=1.23.0 (3)&applicationInfo.merchantDevice.os=iOS&applicationInfo.merchantDevice.osVersion=15.5&metadata.employeeNumber=1&shopperEmail=S.Hopper@example.com&shopperReference=CUST01_34582&tenderOption=ReceiptHandler,AskGratuity

  2. Make a payment request with:

    • SaleData.SaletoAcquirerData: your string of form-encoded key-value pairs.
    {
    "SaleToPOIRequest": {
        "PaymentRequest":{
            "SaleData":{
                "SaleToAcquirerData": "applicationInfo.externalPlatform.name=NewStore&applicationInfo.externalPlatform.integrator=NewStore&applicationInfo.externalPlatform.version=1.0&applicationInfo.merchantApplication.name=NewStore Associate App&applicationInfo.merchantApplication.version=1.23.0 (3)&applicationInfo.merchantDevice.os=iOS&applicationInfo.merchantDevice.osVersion=15.5&metadata.employeeNumber=1&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.externalPlatform.name=NewStore&applicationInfo.externalPlatform.integrator=NewStore&applicationInfo.externalPlatform.version=1.0&applicationInfo.merchantApplication.name=NewStore Associate App&applicationInfo.merchantApplication.version=1.23.0 (3)&applicationInfo.merchantDevice.os=iOS&applicationInfo.merchantDevice.osVersion=15.5&metadata.employeeNumber=1&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 the SaleToAcquirerData: form-encoded key-value pairs. This contains:

    • The metadata passed in the request.
    • The shopperReference and shopperEmail passed in the request.
    • Data resulting from the processing of the payment.
    Form-encoded AdditionalResponse 
    {
    "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=A000000004101001&transactionType=GOODS_SERVICES&backendGiftcardIndicator=false&posadditionalamounts.originalAmountValue=1099&expiryYear=2028&acquirerAccountCode=TestPmmAcquirerAccount&alias=M469509594859802&posAmountGratuityValue=100&gratuityAmount=100&giftcardIndicator=false&authorisedAmountValue=1199&retry.attempt1.shopperInteraction=POS&pspReference=NC6HT9CRT65ZGN82&paymentMethodVariant=mc&authorisationMid=1000&refusalReasonRaw=APPROVED&batteryLevel=70%25&applicationPreferredName=mc%20en%20gbr%20gbp&acquirerCode=TestPmmAcquirer&store=StoreOne&txtime=10%3a21%3a57&iso8601TxDate=2021-02-16T09%3a21%3a57.0000000%2b0000&cardType=mc&posOriginalAmountValue=1099&offline=false&aliasType=Default&recurring.shopperReference=CUST01_34582&txdate=16-02-2021&paymentMethod=mc&authorisedAmountCurrency=EUR&cvcResult=0%20Unknown&shopperReference=CUST01_34582&shopperEmail=S.Hopper%40gmail.com&startYear=2017&tc=48E77545EFA9E129&avsResult=0%20Unknown&cardIssueNumber=33&mid=1000&merchantReference=983&transactionReferenceNumber=NC6HT9CRT65ZGN82&expiryMonth=02&cardSummary=9999&posadditionalamounts.originalAmountCurrency=EUR&posAuthAmountCurrency=EUR&cardHolderVerificationMethodResults=1F0302&authCode=123456&cardIssuerCountryId=826&adjustAuthorisationData=BQABAQCOKbNB1n%2b8QWkLJIo%2fUxmjXZAQNubT6f8s8lbnrf1rrb4WGrV9fG469QF3vO1K3XFlOUlOjEVEq5QGhvTsT5bs2%2bhKEb%2bFqqqdv3PYcsGqHvt8x4U881EPL2E75my0UEAFDwJzAiPG8mifmFzSdd%2fsYoh%2fsdwyCOwqEYr5K5%2bDP6U6hvjw6DuDgIFY7Ce3hIsAJ%2fdZ7h%2bxQDYRC2KFxZmoXlW23QDvyhmWvvagtH0W8n2w2KYr1SfXnU1k3pejGQrPn6gTsHCGNtltsXDLgShMYvETpBJWmfM5tqWIH0Yoi7HiHjhg2Mvbh3pY0YEMLubuKSuQ5Eo3lQ4lMUBzktVaEHNpnNwCZS6Tm3j0JN0bRf4AALUcHXUIroRFUpCQZ9blwu3ii%2bBqKyWtsCd2674UcZtGk7wQlGzKV42Yaz1IiwqyFGjj497UvJ09EkEtCc7epWYpp6%2b1q6CRNjQkORwGi3iav0Us4JNCyStjqN0rrmuJukGkg5MjBdeht%2bDBZq%2b67ZADJInnT7hRKk0s9J%2btQWlRgdZon%2bZKIw2L7%2fzec1EMeDZzhSB6B0FEyrOPzlOw32GQMSLO1JiK6YVjG09EWDuLwqC4AtVyJpwCFElTrQJt6RXjZbr41GulffUiXAhAZcMFrDRsD5u8qJTf8y9Ys7%2fsHyhpWomsCDfPNjZwA0yaV9QV2ebFUJqLcO4Robnz%2fF4fosscvWsp%2bUJGbi4EpwZ6cmDK0dKn%2bHCRv3W9bCyTxeu6FriRSpwLdZoW8J7ilz5MIM1nteAQcSWAkGA5hLq%2fb6dzQh1hkql%2fitcuNROJlsXsy2Zunhx%2bA662zSPcozfNWsZgvMh%2fP49GD5K2wQWKVfpjCMs%2b8Jj83mntJrfEKs%2bkLwY%3d&posAmountCashbackValue=0&posEntryMode=CLESS_CHIP&startMonth=01&fundingSource=CREDIT&metadata.employeeNumber=1&issuerCountry=GB&cardScheme=mc&cardBin=541333&posAuthAmountValue=1199&posadditionalamounts.gratuityAmount=100"
            }
        },
        "MessageHeader": {...}
    }
}

See also