PIN Request

Used to request PIN input on the terminal. Used in combination with DisplayRequest messages from the ECR to the terminal, to inform the cardholder of transaction status.

See [7] for additional information.

Example request

{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "ProtocolVersion": "3.1",
      "MessageClass": "Device",
      "MessageCategory": "PIN",
      "MessageType": "Request",
      "SaleID": "ECR123",
      "POIID": "AT12345",
      "DeviceID": "14"
    },
    "PINRequest": {
      "PINRequestType": "PINEnter",
      "AePINSessionTimeout": 30000,
      "AePINEnterMessage" : "PIN_FIRST_TRY",
	  "AeDisplayBrand": "MyPaymentBrand",
      "AdditionalInput": "1234567890123456",
      "AeAccessibilityMode": true
	  "PaymentTransaction": {
        "AmountsReq": {
          "RequestedAmount": 123
        }
     }
   }
  }
}

Property	Description	Mandatory / Optional
PINRequest		Mandatory
PINRequestType	Enum: PINEnter. The PIN is entered by the Cardholder, encrypted by the terminal, and encrypted PIN Block is provided as result back to ECR.
AePINSessionTimeout	Timeout in milliseconds for how long the terminal waits for either a DisplayRequest from ECR with transaction completion status, or a new PINRequest in case of wrong PIN. The timer starts after the corresponding PINResponse is sent to the ECR.	Mandatory
AePINEnterMessage	Enum: PIN_FIRST_TRY, PIN_TRY_AGAIN, PIN_LAST_TRY. Used to control the message shown to the cardholder during PIN entry.	Mandatory
AeDisplayBrand	Payment brand name. Will be displayed on the PIN enter screen.	Mandatory
AdditionalInput	The "PAN" of the card. Which can be a real PAN or some card nr, userId etc. Please contact Aera to agree on the value(s) / format to be used for your use case.	Mandatory
AeAccessibilityMode	Boolean. Enable accessibility mode for transaction. Default is false.	Optional
PaymentTransaction		Mandatory
AmountsReq		Mandatory
RequestedAmount	Transaction amount. Will be displayed on the PIN enter screen.	Mandatory

Example response

{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "ProtocolVersion": "3.1",
      "MessageClass": "Device",
      "MessageCategory": "PIN",
      "MessageType": "Response",
      "SaleID": "ECR123",
      "POIID": "AT12345",
      "DeviceID": "14",   
    },
    "PINResponse": {
      "Response": {
        "Result": "Success"
        },
      "CardholderPIN": {
        "AeEncrPINBlock": "C8F397C71AC88882A447FE2EFC115192",
        "PINFormat": "ISO4",
        "AeKeySerialNumber": "1AC88882A447FE2E",
        "AdditionalInput": "1234567890123456"
      }
    }
  }
}

Property	Description	Mandatory / Optional
PINResponse		Mandatory
Response		Mandatory
Result	Result of message processing. 'Success' or 'Failure'	Mandatory
CardholderPIN		Mandatory
AeEncrPINBlock	The encrypted PIN Block	Mandatory
PINFormat	Enum: ISO4	Mandatory
AeKeySerialNumber	Key serial number	Mandatory
AdditionalInput	The "PAN" of the card.	Mandatory