Make a payment

Outlines making a basic card payment from your sale system using the Terminal API.


Make the most basic type of PaymentRequest to the nexo endpoint: a card payment with no tender options, additional data or extra functionality. 

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

The SaleID and ServiceID in the MessageHeader should be unique. SaleID and ServiceID combinations are rejected if used recently, within 48 hours.

For a list of Payment Request fields, see PaymentRequest fields.

To support analysis and troubleshooting of payments, pass Integrator and AppName in additional data. For more information, see Pass additional data using the Terminal API.

PaymentRequest
{  
   "SaleToPOIRequest":{  
      "MessageHeader":{  
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "MessageType":"Request",
         "ServiceID":"0207111104",
         "SaleID":"POSSystemID12345",
         "POIID":"MX925-289173817"
      },
      "PaymentRequest":{  
         "SaleData":{  
            "SaleTransactionID":{  
               "TransactionID":"27908",
               "TimeStamp":"2018-02-07T10:11:04+00:00"
            }
         },
         "PaymentTransaction":{  
            "AmountsReq":{  
               "Currency":"EUR",
               "RequestedAmount":10.99
            }
         }
      }
   }
}

The SaleTransactionID TimeStamp must be a current timestamp. The payment will be rejected if it is more than 24 hours before or after the timestamp.

Use our POS test card numbers to test your integration.

Response

For a list of Payment Response fields, see PaymentResponse fields.

An authorisation is attempted and you receive a response with the following fields:


PaymentResponse
{
   "SaleToPOIResponse":{
      "PaymentResponse":{
         "Response":{
            "AdditionalResponse":"cardHolderVerificationMethodResults=1E0000&AID=A000000004101001&applicationPreferredName=mc%20nl&tid=12000000&tc=2ACC0CDC271BE6C3&pspReference=9815179982823824&shopperReference=Mr.%20Big%20Spender&transactionType=GOODS_SERVICES&offline=false&mid=1009&shopperEmail=big%40spender.com&cardHolderName=TC02_MC_Approved",
            "Result":"Success"
         },
         "PaymentResult":{
            "PaymentAcquirerData":{
               "AcquirerTransactionID":{
                  "TransactionID":"9815179982823824",
                  "TimeStamp":"2018-02-07T10:11:01.000Z"
               },
               "MerchantID":"TestMerchantPOS",
               "AcquirerPOIID":"MX925-289173817"
            },
            "AuthenticationMethod":[
               "SignatureCapture"
            ],
            "PaymentInstrumentData":{
               "CardData":{
                  "CardCountryCode":"056",
                  "EntryMode":[
                     "ICC"
                  ],
                  "MaskedPan":"541333 **** 9999",
                  "PaymentBrand":"eftpos_australia",
                  "SensitiveCardData":{
                     "CardSeqNumb":"53",
                     "ExpiryDate":"0228"
                  }
               },
               "PaymentInstrumentType":"Card"
            },
            "AmountsResp":{
               "AuthorizedAmount":10.99,
               "Currency":"EUR"
            },
            "CapturedSignature":{
               "SignaturePoint":[
                  {
                     "X":"271",
                     "Y":"5A"
                  },
              [...]
                  {
                     "X":"FFFF",
                     "Y":"FFFF"
                  }
               ]
            }
         },
         "PaymentReceipt":[
            {
               "OutputContent":{
                  "OutputFormat":"Text",
                  "OutputText":[
                     {
                        "CharacterStyle":"Bold",
                        "EndOfLineFlag":true,
                        "Text":"key=header1&name=Adyen"
                     },
                     {
                        "EndOfLineFlag":true,
                        "Text":"key=header2&name=www.adyen.com"
                     },
                    [...]
                     {
                        "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":"oLkO001517998261000.9815179982823824",
               "TimeStamp":"2018-02-07T10:11:01.000Z"
            }
         },
         "SaleData":{
            "SaleTransactionID":{
               "TransactionID":"27908",
               "TimeStamp":"2018-02-07T10:11:04.000Z"
            }
         }
      },
      "MessageHeader":{
         "SaleID":"POSSystemID12345",
         "ProtocolVersion":"3.0",
         "MessageType":"Response",
         "POIID":"MX925-289173817",
         "ServiceID":"0207111104",
         "MessageClass":"Service",
         "MessageCategory":"Payment"
      }
   }
}
PaymentResponse - Partial
{  
   "SaleToPOIResponse":{  
      "MessageHeader":{  
         "SaleID":"POSSystemID12345",
         "ServiceID":"6625",
         "MessageCategory":"Payment",
         "MessageType":"Response",
         "POIID":"MX925-260193322",
         "ProtocolVersion":"3.0",
         "MessageClass":"Service"
      },
      "PaymentResponse":{  
         "Response":{  
            "Result":"Partial"
         },
         "PaymentReceipt":[  
            "..."
         ],
         "POIData":{  
            "POITransactionID":{  
               "TransactionID":"oLkO001500456032000",
               "TimeStamp":"2017-07-19T09:20:32.000Z"
            }
         },
         "SaleData":{  
            "SaleTransactionID":{  
               "TransactionID":"2771",
               "TimeStamp":"2017-07-19T09:20:37.000Z"
            },
            "TokenRequestedType":"Customer"
         },
         "PaymentResult":{  
            "PaymentInstrumentData":{  
               "CardData":{  
                  "CardCountryCode":"056",
                  "SensitiveCardData":{  
                     "ExpiryDate":"0228",
                     "CardSeqNumb":"53"
                  },
                  "PaymentToken":{  
                     "TokenRequestedType":"Customer",
                     "TokenValue":"K722246565280932"
                  },
                  "EntryMode":[  
                     "ICC"
                  ],
                  "PaymentBrand":"eftpos_australia",
                  "MaskedPan":"541333 **** 9999"
               },
               "PaymentInstrumentType":"Card"
            },
            "AmountsResp":{  
               "Currency":"EUR",
               "AuthorizedAmount":0.39
            },
            "CapturedSignature":{  
               "SignaturePoint":[  
                  "..."
               ]
            },
            "PaymentAcquirerData":{  
               "AcquirerPOIID":"MX925-260193322",
               "AcquirerTransactionID":{  
                  "TransactionID":"9815004560613134",
                  "TimeStamp":"2017-07-19T09:20:32.000Z"
               },
               "AcquirerID":"TestMerchantPOS"
            }
         }
      }
   }
}
PaymentResponse - Cancelled by merchant
{
   "SaleToPOIResponse" : {
      "MessageHeader" : {
         "ServiceID" : "24285",
         "POIID" : "MX925-260193322",
         "ProtocolVersion" : "3.0",
         "MessageCategory" : "Payment",
         "MessageClass" : "Service",
         "SaleID" : "POSSystemID12345",
         "MessageType" : "Response"
      },
      "PaymentResponse" : {
         "Response" : {
            "AdditionalResponse" : "104 Merchant cancelled tx",
            "Result" : "Failure",
            "ErrorCondition" : "Aborted"
         },
         "SaleData" : {
            "TokenRequestedType" : "Customer",
            "SaleTransactionID" : {
               "TimeStamp" : "2017-08-22T11:00:34.000Z",
               "TransactionID" : "17481"
            }
         },
         "POIData" : {
            "POITransactionID" : {
               "TimeStamp" : "2017-08-22T11:00:23.000Z",
               "TransactionID" : "oLkO001503399623002"
            }
         },
         "PaymentResult" : {
            "PaymentAcquirerData" : {
               "MerchantID" : "TestMerchantPOS",
               "AcquirerPOIID" : "MX925-260193322"
            },
            "PaymentInstrumentData" : {
               "PaymentInstrumentType" : "Card",
               "CardData" : {
                  "EntryMode" : []
               }
            }
         }
      }
   }
}

Dynamic Currency Conversion allows your shoppers to pay in their home currency when using Visa and Mastercard.. The terminal must be configured to allow DCC.

Contact POS Support Team to enable this setting.

When the terminal detects a card with a default currency that differs from the merchant’s currency, it offers DCC to the shopper. The terminal displays full details of the exchange rate to the shopper to help the shopper decide whether to convert. The same information is displayed on the Cash Register for the merchant.

The shopper either accepts or rejects the DCC offer and proceeds with the selected amount and currency. If DCC is selected, related information is shown on the receipt.

If you enable Dynamic Currency Conversion (DCC), and perform a DCC transaction, the following data is returned, including the CurrencyConversion element:

{
   "SaleToPOIResponse" : {
      "PaymentResponse" : {
         "PaymentResult" : {
            "PaymentInstrumentData" : {
               "PaymentInstrumentType" : "Card",
               "CardData" : {
                  "PaymentAccountRef" : "C113544884995822",
                  "MaskedPan" : "541333 **** 9990",
                  "CardCountryCode" : "840",
                  "PaymentBrand" : "MCDCCFR",
                  "SensitiveCardData" : {
                     "ExpiryDate" : "0228",
                     "CardSeqNumb" : "72"
                  },
                  "EntryMode" : [
                     "ICC"
                  ]
               }
            },
            "CurrencyConversion" : [
               {
                  "Rate" : 1.6178,
                  "CustomerApprovedFlag" : true,
                  "ConvertedAmount" : {
                     "Currency" : "USD",
                     "AmountValue" : 17.78
                  },
                  "Markup" : 3
               }
            ],
            "AmountsResp" : {
               "AuthorizedAmount" : 10.99,
               "Currency" : "EUR"
            }
         },
         "Response" : {
            "Result" : "Success"
         },
         "SaleData" : {
            "SaleTransactionID" : {
               "TimeStamp" : "2017-06-07T08:26:04.000Z",
               "TransactionID" : "1667"
            }
         },
         "POIData" : {
            "POITransactionID" : {
               "TransactionID" : "oLkO001496823914001.9815033996072250",
               "TimeStamp" : "2017-06-07T08:25:14.000Z"
            }
         },
         "PaymentReceipt" : [ ... ]
         ]
      },
      "MessageHeader" : {
         "ProtocolVersion" : "3.0",
         "POIID" : "MX925-123456789",
         "MessageType" : "Response",
         "MessageClass" : "Service",
         "MessageCategory" : "Payment",
         "SaleID" : "POSSystemID12345",
         "ServiceID" : "11915"
      }
   }
}


Payment responses can also include additional form encoded data. For example:

{  
   "AdditionalResponse":"message=108%20Shopper%20cancelled%20tx&tid=12000000&merchantReference=1186&txdate=07-11-2017&transactionType=GOODS_SERVICES&txtime=11%3a20%3a55"
}

The POITransactionID returned by the Terminal API consists of a PSP reference and a Tender reference. The format of the TransactionID is: < tenderref>.<pspref>, for example, oLkO001503399575001.9815033996072250.

If a PSP reference has not yet been generated, the TransactionID will only consist of a tender reference. This could occur if the transaction was completed offline.

Not all data in a payment response will always be available. The availability of some data depends on an internet connection and the payment method used.