PIN

Message category	Class
`PIN`	Device

📘
Used in these guides
Connect your ECR · Display and PIN

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. For the full flow, see PIN entry controlled by the ECR. Ask your Aera contact for the appendix that describes the full PIN message flow.

Example request and response

All fields

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

Field	Required	Description
`PINRequest`	Required	Contains the fields below
↳ `PINRequestType`	Required	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.
↳ `AePINEnterMessage`	Required	Enum: PIN_FIRST_TRY, PIN_TRY_AGAIN, PIN_LAST_TRY. Used to control the message shown to the cardholder during PIN entry.
↳ `AeDisplayBrand`	Required	Payment brand name. Will be displayed on the PIN enter screen.
↳ `AdditionalInput`	Required	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.
↳ `AeAccessibilityMode`	Optional	Boolean. Enable accessibility mode for transaction. Default is false.
↳ `PaymentTransaction`	Required	Contains the fields below
↳ `AmountsReq`	Required	Contains the fields below
↳ `RequestedAmount`	Required	Transaction amount. Will be displayed on the PIN enter screen.

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

Field	Required	Description
`PINResponse`	Required	Contains the fields below
↳ `Response`	Required	Contains the fields below
↳ `Result`	Required	Result of message processing. 'Success' or 'Failure'
↳ `CardholderPIN`	Required	Contains the fields below
↳ `AeEncrPINBlock`	Required	The encrypted PIN Block
↳ `PINFormat`	Required	Enum: ISO4
↳ `AeKeySerialNumber`	Required	Key serial number
↳ `AdditionalInput`	Required	The "PAN" of the card.