Implement the payment flow

Integrate your ECR · task 5 of 8

This task covers the requests and features every ECR must support before going live. Your ECR can already connect and open a session (see Connect your ECR).

Every ECR needs to:

Make a payment, with a Payment request.
Cancel an in-progress payment, with an Abort request.
Generate receipts from the receipt data in the payment response.
Verify transaction status when a response is lost, with a TransactionStatus request.
Check the connection to the terminal and the payment host, with a Diagnosis request.
Handle events from the terminal, with Event notifications.
Handle responses and timeouts for every request.

Together with Login and Logout from task 4, this is the minimum message set. Everything else, such as refunds, reversals and cashback, is optional: see Add optional features.

An in-store payment

Your ECR

Terminal

Aera

1Login

Step 1 of 7 · Your ECR → TerminalYour ECR opens a session with the terminal. Do it once, before anything else.

2Login response

Step 2 of 7 · Terminal → Your ECRResult Success: the terminal is ready. The response also lists the card brands it accepts.

3Payment

Step 3 of 7 · Your ECR → TerminalYour ECR sends the amount and its own transaction ID.

4Display: WAITING_FOR_CARD

Step 4 of 7 · Terminal → Your ECRThe terminal tells your ECR what it's doing. Show it to the cashier.

Customer taps, inserts or swipes the card

MeanwhileAbove the contactless limit, the terminal asks for the PIN.

5Authorisation

Step 5 of 7 · Terminal → AeraThe terminal asks for approval.

6Approved

Step 6 of 7 · Aera → TerminalAera answers the terminal.

7Payment response: AeResponseCode 000

Step 7 of 7 · Terminal → Your ECRYour ECR reads AeResponseCode (0xx is approved) and prints the receipt text exactly as it comes.

Your ECR

Terminal

Aera

1
Your ECR → Terminal
Login
Your ECR opens a session with the terminal. Do it once, before anything else.
2
Terminal → Your ECR
Login response
Result Success: the terminal is ready. The response also lists the card brands it accepts.
3
Your ECR → Terminal
Payment
Your ECR sends the amount and its own transaction ID.
4
Terminal → Your ECR
Display: WAITING_FOR_CARD
The terminal tells your ECR what it's doing. Show it to the cashier.
·
Meanwhile
Customer taps, inserts or swipes the card
Above the contactless limit, the terminal asks for the PIN.
5
Terminal → Aera
Authorisation
The terminal asks for approval.
6
Aera → Terminal
Approved
Aera answers the terminal.
7
Terminal → Your ECR
Payment response: AeResponseCode 000
Your ECR reads AeResponseCode (0xx is approved) and prints the receipt text exactly as it comes.

Minimum message set

Message	Why	Guide
Login and Logout	Open and close a session	Open a session
Payment	Take a payment	Make a payment
Abort	Cancel a payment from the ECR	Cancel an in-progress payment
TransactionStatus	Find the result if a response was lost	Verify transaction status
Diagnosis	Check the connection to the terminal and host	Check the connection
Event	Handle notifications from the terminal, including rejects of messages it can't read	Handle events

Rules for every ECR

Ignore fields you don't recognise. New fields are added over time, and an unknown field must not make your ECR fail.
Show Display messages to the cashier. They can arrive at any time during a transaction. Don't rely on their order, number or text: these can change with the terminal's software version and language.
Never charge twice. If a response is lost, reconnect if needed and check TransactionStatus before you try again.
Use UTF-8.

Specifications

Messages: every message, with full examples and all fields.
Nexo Retailer specifications (NIS v4 package). Aera's XSD file for this implementation is available on request from Aera.