Payment

Outlines how to make a payment using the Terminal API.


Not all operations are available for each type of gift card. For an overview of supported features for the different types, see Gift Card Overview

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 Payment Request fields, see PaymentRequest fields.

The elements of a gift card payment request are wrapped in a PaymentRequest envelope. A PaymentRequest envelope must contain a SaleData object and a PaymentTransaction object.

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.

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

A PaymentRequest can include additional form-encoded key-value pairs in the SaleToAcquirerData field. This can include data to create recurring contracts.

The fields described below are the basic payment fields you specify when making a PaymentRequest call to the Terminal API.

PaymentRequest
{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "MessageType":"Request",
         "ServiceID":"0326111341",
         "SaleID":"POSSystemID12345",
         "POIID":"MX925-286240330"
      },
      "PaymentRequest":{
         "SaleData":{
            "SaleTransactionID":{
               "TransactionID":"31915",
               "TimeStamp":"2018-03-26T09:13:41+00:00"
            }
         },
         "PaymentTransaction":{
            "AmountsReq":{
               "Currency":"GBP",
               "RequestedAmount":100.99
            }
         },
         "PaymentData":{
            "PaymentInstrumentData":{
               "PaymentInstrumentType":"StoredValue",
               "StoredValueAccountID":{
                  "StoredValueAccountType":"GiftCard",
                  "EntryMode":[
                     "Scanned"
                  ],
                  "StoredValueProvider":"goldsmiths",
                  "IdentificationType":"PAN",
                  "StoredValueID":"9826150911219687",
                  "ExpiryDate":"1117"
               }
            }
         }
      }
   }
}

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":{
         "POIData":{
            "POITransactionID":{
               "TimeStamp":"2018-03-26T09:22:16.000Z",
               "TransactionID":"oLkO001522056136000.9815220561432452"
            }
         },
         "SaleData":{
            "SaleTransactionID":{
               "TimeStamp":"2018-03-26T09:22:21.000Z",
               "TransactionID":"23860"
            },
         },
         "PaymentReceipt":[
            {
               "DocumentQualifier":"CashierReceipt",
               "OutputContent":{
                  "OutputFormat":"Text",
                  "OutputText":[
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=Adyen&key=header1",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=www.adyen.com&key=header2",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=MERCHANT%20COPY&key=merchantTitle",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Date&value=26%2f03%2f18&key=txdate",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Time&value=11%3a22%3a16&key=txtime",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Card&value=%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a9687&key=pan",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Pref.%20name&key=preferredName",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Card%20type&value=goldsmithsgiftcard&key=cardType",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Payment%20method&value=goldsmithscard&key=paymentMethod",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Payment%20variant&value=goldsmithsgiftcard&key=paymentMethodVariant",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Entry%20mode&value=MKE&key=posEntryMode",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=MID&value=0004&key=mid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=TID&value=MX925-286240330&key=tid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=PTID&value=12000000&key=ptid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=ATC&key=atc",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Buyer%20ID&key=buyerId",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Operation%20type&key=walletOperationType",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Transaction%20ref.&key=walletTransactionReference",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=DCC%20amount&key=walletDccAmount",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=DCC%20rate&key=walletDccRate",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Tender&value=oLkO001522056136000&key=txRef",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Reference&value=23860&key=mref",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Type&value=GOODS_SERVICES&key=txtype",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=TOTAL&value=%c2%a3%20100.99%20%20&key=totalAmount",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=APPROVED&key=approved",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     }
                  ]
               }
            },
            {
               "DocumentQualifier":"CustomerReceipt",
               "OutputContent":{
                  "OutputFormat":"Text",
                  "OutputText":[
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=Adyen&key=header1",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=www.adyen.com&key=header2",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=CARDHOLDER%20COPY&key=cardholderHeader",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Date&value=26%2f03%2f18&key=txdate",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Time&value=11%3a22%3a16&key=txtime",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Card&value=%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a9687&key=pan",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Pref.%20name&key=preferredName",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Card%20type&value=goldsmithsgiftcard&key=cardType",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Payment%20method&value=goldsmithscard&key=paymentMethod",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Payment%20variant&value=goldsmithsgiftcard&key=paymentMethodVariant",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Entry%20mode&value=MKE&key=posEntryMode",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=MID&value=%2a%2a%2a%2a%2a%2a%2a%2a%2a0004&key=mid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=TID&value=MX925-286240330&key=tid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=PTID&value=12000000&key=ptid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=ATC&key=atc",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Buyer%20ID&key=buyerId",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Operation%20type&key=walletOperationType",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Transaction%20ref.&key=walletTransactionReference",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=DCC%20amount&key=walletDccAmount",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=DCC%20rate&key=walletDccRate",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Tender&value=oLkO001522056136000&key=txRef",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Reference&value=23860&key=mref",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Type&value=GOODS_SERVICES&key=txtype",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=TOTAL&value=%c2%a3%20100.99%20%20&key=totalAmount",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=APPROVED&key=approved",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Please%20retain%20for%20your%20records&key=retain",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Thank%20you&key=thanks",
                        "EndOfLineFlag":true
                     }
                  ]
               }
            }
         ],
         "PaymentResult":{
            "PaymentAcquirerData":{
               "AcquirerPOIID":"MX925-286240330",
               "AcquirerTransactionID":{
                  "TimeStamp":"2018-03-26T09:22:16.000Z",
                  "TransactionID":"9815220561432452"
               },
               "MerchantID":"TestMerchantPOS"
            },
            "PaymentInstrumentData":{
               "StoredValueAccountID":{
                  "IdentificationType":"PAN",
                  "EntryMode":[
                     "Scanned"
                  ],
                  "StoredValueID":"9826150911219687",
                  "StoredValueAccountType":"GiftCard",
                  "StoredValueProvider":"goldsmiths",
                  "ExpiryDate":"1117"
               },
               "PaymentInstrumentType":"StoredValue"
            },
            "AmountsResp":{
               "AuthorizedAmount":100.99,
               "Currency":"GBP"
            },
            "PaymentType":"Normal"
         },
         "Response":{
            "Result":"Success",
            "AdditionalResponse":"tid=12000000&transactionType=GOODS_SERVICES&pspReference=9815220561432452&currentBalanceCurrency=GBP&offline=false&mid=0004&giftcardPAN=9826150911219687&currentBalanceValue=977401"
         }
      },
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "SaleID":"POSSystemID12345",
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "ServiceID":"0326112221",
         "POIID":"MX925-286240330",
         "MessageType":"Response"
      }
   }
}

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.