Payment

A Payment request initiates a financial transaction by processing the specified amount using the presented card and the negotiated session context. Upon approval, the transaction is authorized and completed according to the supported payment application and terminal capabilities

Example request

{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "ProtocolVersion": "3.1",
      "ServiceID": "2",
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "SaleID": "ECR123",
      "POIID": "AT12345"
    },
    "PaymentRequest": {
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "12345678",
          "TimeStamp": "2024-04-18T22:16:13.178+02:00"
        },
        "AeSaleToHostData": "{\"VoucherProductcode\":\"200001#\"}",
        "AeDisplayText": "Loyalty registered"
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "RequestedAmount": 123
        },
        "TransactionConditions": {
          "AllowedPaymentBrand": [
            "VISA",
            "MASTERCARD"
          ],
          "AeAllowedPaymentBrandCategory": [
            "VOUCHER"
          ],
          "AeAccessibilityMode": true
        }
      },
      "PaymentData": {
        "PaymentType": "Normal"
      }
    }
  }
}

Property	Description	Mandatory / Optional
PaymentRequest		Mandatory
SaleData		Mandatory
SaleTransactionID		Mandatory
TransactionID	ECR provided transaction ID. Max length: 35	Mandatory
TimeStamp	Timestamp of request from ECR	Mandatory
AeSaleToHostData	Stringified Json. Used to pass through data from the ECR to the acquirer or issuer. E.g., for C-TAP Product Code or for a list of purchased items, see supported keys/values below.	Optional
AeDisplayText	Text that will be displayed on the transaction completion screen for approved transactions.	Optional
AeIFlag	BankAxept KIB ("kontanttjenester i butikk") "fraud suspicion" flag, also called I-flag.	Optional
PaymentTransaction		Mandatory
AmountsReq		Mandatory
RequestedAmount	Payment amount	Mandatory
TransactionConditions	Specify transaction conditions or restrictions for the current transaction	Optional
AllowedPaymentBrand	List of allowed payment brands for the current transaction. See [4] for supported values	Optional
AeAllowedPaymentBrandCategory	List of allowed payment brand categories for the current transaction. See [4] for supported values	Optional
AeAccessibilityMode	Boolean. Enable accessibility mode for transaction. Default is false.	Optional
PaymentData		Mandatory
PaymentType	Enum: Normal, Refund. 'Normal' is used for a standard purchase.	Mandatory
CardAcquisitionReference	Mandatory if referring to a prior CardAcquisition (e.g. for loyalty lookup), otherwise absent	Optional
TransactionID	TransactionID in POITransactionID from the CardAcquistionResponse	Optional
TimeStamp	Timestamp in POITransactionID from the CardAcquistionResponse	Optional

Note: The AeSaleToHostData is a field used for passing data from ECR to the Acquirer or Issuer. The AeHostToSaleData is a similar additional field in the response message, used for passing data the other way, from Issuer or Acquirer to ECR. Generally, there may be more than one JSON structure in the fields, e.g. ”{"Structure1":{"DataElementList1":[100, 200]},"Structure2":{"DataElementList2":["xxx","yyy","zzz"]}}”. Structures not relevant or not supported by the ECR must be ignored.
The content of those fields must be in stringified Json format and the keys / properties used inside must be supported by Aera before they can be used.

Currently supported keys

Key	Description
VoucherProductcode	Voucher product code. Example: `"200001"` for a meal voucher.
PurchasedItems	Structure containing a list of purchased items with the fields listed below. Example: `{"PurchasedItems":[{"ProductCode":"1000","GrossAmount":125.00,"VatAmount":25.00,"VatPercent":25.0,"ItemQuantity":2,"UnitOfMeasure":"Pieces"}]}`
ProductCode	Product code of the purchased item (string).
GrossAmount	Gross amount of the purchased item, including VAT/tax (decimal).
VatAmount	VAT/tax amount included in `GrossAmount` (decimal).
VatPercent	VAT/tax percentage used to calculate `VatAmount`. Formula: `VatAmount = NetAmount × VatPercent`, `GrossAmount = NetAmount + VatAmount` (decimal).
ItemQuantity	Quantity of the purchased item (decimal).
UnitOfMeasure	Unit for `ItemQuantity`. Allowed values: `"Litre"`, `"Pieces"`, `"Kilo"` (string).

See for complete list of Voucher product codes.

PurchasedItems

Example:

{
  "PurchasedItems": [
    {
      "ProductCode": "1000",
      "GrossAmount": 125.00,
      "VatAmount": 25.00,
      "VatPercent": 25.0,
      "ItemQuantity": 2,
      "UnitOfMeasure": "Pieces"
    }
  ]
}

Example response

{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Payment",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "AT12345",
      "ProtocolVersion": "3.1",
      "SaleID": "ECR123",
      "ServiceID": "2"
    },
    "PaymentResponse": {
      "Response": {
        "AeStan": "123456",
        "AeAcquirerResponseCode": "00",
        "AeResponseCode": "000",
        "AdditionalResponse": "",
        "Result": "Success"
      },
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "12345678",
          "TimeStamp": "2024-04-18T22:16:13.178+02:00"
        },
        "AeSaleToHostData": "{\"VoucherProductcode\":\"200001#\"}",
        "AeHostToSaleData": "  "
      },
      "POIData": {
        "POITransactionID": {
          "TransactionID": "87654321",
          "TimeStamp": "2024-04-18T22:16:20.178+02:00"
        }
      },
      "PaymentResult": {
        "PaymentInstrumentData": {
          "CardData": {
            "SensitiveCardData": {
              "ExpiryDate": "2701"
            },
            "CardCountryCode": "578",
            "MaskedPAN": "540481******1761",
            "PaymentBrand": "MASTERCARD",
			"AeCardBrandCode": "05"
          },
          "PaymentInstrumentType": "Card"
        },
        "AmountsResp": {
          "AuthorizedAmount": 123
        },
        "PaymentAcquirerData": {
          "ApprovalCode": "541639",
          "MerchantID": "6815413"
        },
        "AuthenticationMethod": [
          "OfflinePIN"
        ],
		"OnlineFlag": "true"
      },
      "PaymentReceipt": [
        {
	      "DocumentQualifier": "CustomerReceipt",
          "OutputContent": {
            "OutputText": [
              {
                "Text": "Receipt text 1"
              },
              {
                "Text": "Receipt text 2"
              },
              {
                "Text": "Receipt text 3"
              }
            ]
          }
        }
      ]
    }
  }
}

Property	Description	Mandatory / Optional
PaymentResponse		Mandatory
Response		Mandatory
Result	Success, Failure or Partial	Mandatory
AeStan	STAN of transaction	Optional
AeAcquirerResponseCode	Response code from the acquirer. For information and logging purposes only.	Optional
AeResponseCode	Aera response code. The ECR shall use this response code. See [6] for complete list of response codes	Mandatory
AdditionalResponse	Additional information related to processing status of a message request	Optional
SaleData	Copied from request, optionally AeHostToSaleData in addition.	Mandatory
POIData		Mandatory
POITransactionID		Mandatory
TransactionID	Transaction ID generated by Aera	Mandatory
TimeStamp		Mandatory
POIReconciliationID	The global ReconciliationID provided by Aera	Optional
PaymentResult		Optional
PaymentInstrumentData	Information about the payment instrument used for transaction. CardCountryCode is provided in ISO 3166-1 numeric See [4] for supported values for the PaymentBrand property. AeCardBrandCode contains the PIT/Card Type	Optional
OnlineFlag	Indicate that the payment transaction processing has required the approval of a host.	Optional
AmountsResp		If Result is Success or Partial
AuthorizedAmount	The amount authorized by the Acquirer for the payment transaction. This will be the partially authorized amount in case of partial approval.	If Result is Success or Partial
PaymentAcquirerData		Optional
ApprovalCode	Transaction authorisation code	Optional
MerchantID	Merchant ID	Mandatory
AuthenticationMethod	Method used for customer authentication.	Optional
PaymentReceipt	Pre-formatted terminal receipt provided to the ECR for printing. Note: the content is for printing purposes only - the ECR must not parse the strings, as they could change between application versions	Optional

Note: if DCC support is configured on the terminal and the transaction is eligible for DCC, the cardholder will be shown the DCC terms and asked to select currency. A transaction performed with DCC does not affect the messages between ECR and terminal, other than that the receipt texts will include the mandated DCC information.