Payment

Perform a normal payment, e.g. a normal purchase transaction.

Example request and response

All fields

{
  "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"
      }
    }
  }
}

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

See Voucher product codes for the complete list.

{
  "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"
              }
            ]
          }
        }
      ]
    }
  }
}

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.

Payment with loyalty lookup

If the ECR wants a loyalty lookup before initiating a payment, the ECR first initiates a CardAcquisition request. Based on the LoyaltyId in the CardAcquisition response, the ECR may choose to store loyalty points earned and/or update the amount in the Payment request that follows the CardAcquisition request. The following Payment request refers to the preceding CardAcquisition request. In this way, no additional acquisition of card data is needed, and the payment can be performed as a single tap transaction.

In the CardAcquisition request, relevant payment data needs to be provided, including the amount. The amount in the following Payment request must not exceed the amount of the CardAcquisition request. if cashback amount was spesified in the CardAcquisition request, it must also be sent in the following Payment request. The PaymentType value must also be the same as was used in the CardAcquisition request.

The Payment request must include a reference to the preceding CardAcquisition reference. The data are found in the POITransactionID data structure of the CardAcquisition response and are added to the CardAcquisitionReference of the PaymentData data structure of the Payment 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"
        }
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "RequestedAmount": 123
        }
      },
      "PaymentData": {
        "PaymentType": "Normal",
        "CardAcquisitionReference": {
          "TransactionID": "87654321"
        }
      }
    }
  }
}

Payment with cashback

Payment with cashback is used when the customer requests an amount to be paid in cash from the merchant to the customer. The amount is then added to the requested amount in the payment request.

Payment with cashback is performed as a Payment request. The cashback amount is added as CashBackAmount in the AmountsReq data structure of the Payment request. The format is the same as for RequestedAmount. The RequestedAmount includes the CashBackAmount. The approved cashback amount is included as CashBackAmount in the AmountsResp data structure. The AuthorizedAmount includes the CashBackAmount.

For BankAxept KIB ("kontanttjenester i butikk") cashback the merchant must set a "fraud suspicion" flag, also called I-flag in the message. This flag is included by adding the 'AeIFlag' property into the SaleData data structure as indicated in the example. The value 1 is used if the cashier suspects fraud, otherwise 0. Since the I-flag is sensitive the value of the I-flag shall be masked in the logs.

{
  "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"
        },
        "AeIFlag": 0
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "RequestedAmount": 223.56,
          "CashBackAmount": 100
        }
      },
      "PaymentData": {
        "PaymentType": "Normal"
      }
    }
  }
}

Cash advance

Cash advance (also called cash withdrawal or cashout) is similar to payment with cashback, but the full amount is paid as cash to the customer.

Cash advance is performed as a Payment request with PaymentType = "CashAdvance". Opposite to payment with cashback, CashBackAmount is neither set in the Payment Request nor included in the Payment response.

For BankAxept KIB ("kontanttjenester i butikk") cash advance the merchant must set a "fraud suspicion" flag, also called I-flag in the message. This flag is included by adding the 'AeIFlag' property into the SaleData data structure, as shown in the example under Payment with cashback. The value 1 is used if the cashier suspects fraud, otherwise 0. Since the I-flag is sensitive the value of the I-flag shall be masked in the logs.

Cash deposit

Cash deposit is used for cash deposits crediting the account associated with the card presented by the customer.

Cash deposit is performed as a Payment request with PaymentType = "CashDeposit".

For BankAxept KIB ("kontanttjenester i butikk") cash deposit the merchant must set a "fraud suspicion" flag, also called I-flag in the message. This flag is included by adding the 'AeIFlag' property into the SaleData data structure, as shown in the example under Payment with cashback. The value 1 is used if the cashier suspects fraud, otherwise 0. Since the I-flag is sensitive the value of the I-flag shall be masked in the logs.

Refund

Payment refund is used for return of goods. The customer presents the card he wants the money refunded to. The refund amount is transferred from the merchant account to the account associated with the payment card presented by the customer.

Refund is performed as a Payment request but the PaymentType is set to "Refund" instead of "Normal".

In the terminal the customer is requested to present the card (tap or insert).

Note: The current version requires the customer to present the card. There is no link or reference to the original transaction and the card used for that transaction. It is up to the merchant to define the amount to be refunded.

Normally, the amount would be equal to or less than the original payment, but the merchant may initiate a higher amount. A refund may be declined by the issuer based on issuer-specific rules and policies. These may include factors such as amount recognition, time elapsed since the original purchase, and the match of specific Merchant IDs. These checks are performed and enforced by the issuer and are therefore outside of Aera's control.