Card Acquisition

Card Acquisition is used to read card data from a card presented by the customer. Afterwards, based the card data and a card reference provided in the Card Acquisition response, the following request types can be performed on the card.

Function	Request type	Description
Payment	Payment	Used to initiate a payment or refund transaction. Since the CardAcquisition response, if available, provides a reference to a customer's loyalty program membership ID, the ECR may collect loyalty points, and/or update the payment amount before sending the Payment request.
Get customer identity	None (abort required)	The customer ID could be returned in CardAcquistion response. If no Payment or BalanceInquiry request is performed after the CardAcquisition request, an abort is required, see Note below
Customer onboarding	None (abort required)	The customer ID could be returned in CardAcquistion response. If no match, the customer could be asked to enter his mobile number in the terminal. Onboarding is then performed out bounds via a link in an SMS. The customer is then linked to the card referenced in CardAcquistion response. If no Payment or BalanceInquiry request is performed after the CardAcquisition request, an abort is required, see Note below
Abort after CardAcquisition requst	EnableService	Se Note below

These functions are described in separate sections.

Note:
If no Payment or BalanceInquiry request is to be performed after a Card Acquisition request, the ECR must send an EnableService request with the TransactionAction component set to “AbortTransaction” to terminate the card processing and remove the card from the card reader.

Example CardAcquisition request

{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "ProtocolVersion": "3.1",
      "ServiceID": "2",
      "MessageClass": "Service",
      "MessageCategory": "CardAcquisition",
      "MessageType": "Request",
      "SaleID": "ECR123",
      "POIID": "AT12345"
    },
    "CardAcquisitionRequest": {      
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "12345678",
          "TimeStamp": "2024-04-18T22:16:13.178+02:00"
        }
      },
      "CardAcquisitionTransaction": {
        "TotalAmount": 125.00,
        "AeCashBackAmount": 200,  
        "PaymentType": "Normal",                          
        "AllowedPaymentBrands": [ 
          "VISA",
          "Mastercard"
        ],
        "AeAllowedPaymentBrandCategory": [
           "VOUCHER"
        ],
        "AeAccessibilityMode": true 
      }
    }
  }
}

Property	Description	Mandatory / Optional
CardAcquisitionRequest		Mandatory
SaleData		Mandatory
SaleTransactionID		Mandatory
TransactionID	ECR provided transaction ID (same as for Payment request). Max length: 35	Mandatory
TimeStamp	Timestamp of request from ECR (same as for Payment requst)	Mandatory
CardAcquisitionTransaction		Mandatory
TotalAmount	Mandatory if the follow up request is Payment, Payment with cashback, or Refund. Otherwise absent.	Optional
AeCashBackAmount	Mandatory if the follow up request is Payment with cashback	Optional
AllowedPaymentBrand	List of allowed payment brands for the current transaction, if restrictions are enforced. See [4] for supported values	Optional
AeAllowedPaymentBrandCategory	List of allowed payment brand categories for the current transaction, if restrictions are enforced. See [4] for supported values	Optional
AeAccessibilityMode	Boolean. Enable accessibility mode for transaction. Default is false.	Optional
PaymentType	Enum: "Normal" or "Refund", or absent. Set to "Normal" if the follow up request is a Payment or Payment with cashback Set to "Refund" if the follow up request is Refund Absent if the follow up request is Balance request, or if CardAcquisition is used to get customer identity only	Optiona

Example CardAcquisition response

{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "ProtocolVersion": "3.1",
      "ServiceID": "2",
      "MessageClass": "Service",
      "MessageCategory": "CardAcquisition",
      "MessageType": "Response",
      "SaleID": "ECR123",
      "POIID": "AT12345"
    },
    "CardAcquisitionResponse": {
      "Response": {
        "Result": "Success",
        "AeResponseCode": "000"
      },
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "12345678",
          "TimeStamp": "2024-04-18T22:16:13.178+02:00"
        }
      },
      "POIData": {
        "POITransactionID": {
          "TransactionID": "87654321",
          "TimeStamp": "2024-04-18T22:16:13.478+02:00"
        }
      },
      "PaymentInstrumentData": {
        "PaymentInstrumentType": "Card",
        "CardData": {
          "PaymentBrand": "MASTERCARD",
          "MaskedPAN": "540481******1761",
          "SensitiveCardData": {
            "ExpiryDate": "2701"
          },
          "CardCountryCode": "578"
        }
      },
      "LoyaltyAccount": [
        {
          "LoyaltyBrand": "Rewards1",
          "LoyaltyAccountID": {
            "LoyaltyID": "LOYALTY1234567890"
          }
        }
      ],
      "AeHostToSaleData": ”{\"AmountAndProductRestrictions\":{\"MaxAmount\": 2000,\"ProductGroupsAllowed\": [100, 200]}}”
    }
  }
}

Property	Description	Mandatory / Optional
CardAcquisitionResponse		Mandatory
Response		Mandatory
Result	Success, Failure or Partial	Mandatory
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 the request	Mandatory
AeHostToSaleData	Stringified Json. Used to pass through data from the host to the ECR, e.g. a list of allowed products	Optional
POIData		Mandatory
POITransactionID		Mandatory
TransactionID	Transaction ID generated by Aera, to be used in the CardAcquisitionReference of the request following the CardAcquisition	Mandatory
TimeStamp	Time stanp, to be used in the CardAcquisitionReference of the request following the CardAcquisition	Mandatory
PaymentInstrumentData	Information about the payment instrument used for transaction, if available CardCountryCode is provided in ISO 3166-1 numeric See [4] for supported values for the PaymentBrand property.	Optional
PaymentInstrumentType	"Card" or "Mobile"	Optional
CardData		Optional
PaymentBrand	Brand of the selected payment card	Optional
MaskedPAN	See PaymentResponse	Optional
PaymentAccountRef	PAR if present, see PaymentResponse	Optional
LoyaltyAccount	List of loyalty look-ups (but normally only one), mandatory if loyalty lookup match, absent if no match	Optional
LoyaltyBrand	The name of the loyalty program	Optional
LoyaltyAccountID	Mandatory if match	Optional
LoyaltyID	The loyalty ID within the loyalty program	Optional
AeHostToSaleData	Stringified JSON. Used to pass through data from the host to the ECR, e.g. a list of allowed products, se supported keys/values/structures below	Optional

Note

The AeHostToSaleData is a in a stringified JSON field used for passing data from the host to the ECR. Generally, there may be more than one JSON structure in the field, e.g. ”{"Structure1":{"DataElementList1":[100, 200]},"Structure2":{"DataElementList2":["xxx","yyy","zzz"]}}”
Structures not relevant or not supported by the ECR must be ignored. The current structures are currentlys supported when applicable:

Currently supported Keys

Key	Description
AmountAndProductRestrictions	Structure containing the maximum allowed purchase amount and a list of allowed product groups. Example: `{"AmountAndProductRestrictions":{"MaxAmount":2000,"ProductGroupsAllowed":[100,200]}}`
MaxAmount	Maximum allowed gross purchase amount (decimal).
ProductGroupsAllowed	List of allowed product groups (array of integers), e.g. `[100, 200]`.