The possibility to read one or more cards before the payment is actually made, makes it possible to know the customer and give a discount on the sale being made. With the possibility comes just a little bit more complexity and logic around messages.
Heads up!: To use this feature the POS side needs to implement a server. Print request might be generated when aborting.
Easy flow reading card before payment request
sequenceDiagram
participant POS
participant Terminal
POS->>Terminal: EnableService Request StartTransaction
Terminal->>POS: EnableService Response success
activate Terminal
loop open all readers for card read
POS->>Terminal: CardAcquisition Request
Terminal->>POS: CardAcquisition Response
Note left of Terminal: Response contains<br/>CNA,<br/>Masked PAN,<br/>Card type,<br/>Card product name
Note left of Terminal: Terminal shows "please wait"
end
POS->>Terminal: Payment Request
deactivate Terminal
Note right of POS: Normal procedure for payment request.<br/>Last payment card read is used
The messages EnableService and CardAcquisition are key to this feature, but when aborting in different situations different messages are used depending on state.
A CardAcquisition is aborted using an AbortRequest but the enabled service is aborted using the EnableServiceRequest AbortTransaction.
Abort while waiting for a card
sequenceDiagram
participant POS
participant Terminal
POS->>Terminal: EnableService Request StartTransaction
Terminal->>POS: EnableService Response success
activate Terminal
POS->>Terminal: CardAcquisition Request
POS->>Terminal: AbortRequest
Terminal-->>POS: Http response 204
deactivate Terminal
Terminal->>POS: CardAcquisition Response
Note left of Terminal: Terminal shows transaction aborted
Note left of Terminal: Terminal goes to idle state
The enabled service Transaction state lasts from the EnableService response until it is aborted or a PaymentRequest is sent. During that state several cardacquisitions may be issued, but if abort is desired after a card acquisition response there is no ongoing request and the state is terminated by the EnableServiceRequest AbortTransaction
Abort sequence after card has been read
sequenceDiagram
participant POS
participant Terminal
POS->>Terminal: EnableService Request StartTransaction
Terminal->>POS: EnableService Response success
activate Terminal
POS->>Terminal: CardAcquisition Request
Terminal->>POS: CardAcquisition Response
POS->>Terminal: EnableServiceRequest AbortTransaction
Terminal->>POS: EnableServiceResponse success
deactivate Terminal
alt payment card was read
Note left of Terminal: Terminal shows transaction aborted
Terminal->>POS: PrintRequest with receipt information
end
Note left of Terminal: Terminal goes to idle state
EnableService
Request
1
2
3
4
5
6
<SaleToPOIRequest>
<MessageHeader ProtocolVersion="3.1" MessageClass="Service" MessageCategory="EnableService" MessageType="Request" ServiceID="3" SaleID="1" POIID="A-POIID" />
<EnableServiceRequest TransactionAction="StartTransaction">
<ServicesEnabled>CardAcquisition</ServicesEnabled>
</EnableServiceRequest>
</SaleToPOIRequest>
| Name | Lev | Attribute | Description |
|---|---|---|---|
| EnableServiceRequest | 1 | TransactionAction | StartTransaction or AbortTransaction. |
| ServiceEnabled | 2 | Only value used is CardAcquisition. |
Response
1
2
3
4
5
6
<SaleToPOIResponse>
<MessageHeader MessageClass="Service" MessageCategory="EnableService" MessageType="Response" ServiceID="3" SaleID="1" POIID="A-POIID" />
<EnableServiceResponse>
<Response Result="Success" />
</EnableServiceResponse>
</SaleToPOIResponse>
Next request following a successful EnableServiceResponse for TransactionAction StartTransaction, is CardAcquisition or EnableService with TransactionAction AbortTransaction.
CardAcquisition
Request
1
2
3
4
5
6
7
8
9
<SaleToPOIRequest>
<MessageHeader ProtocolVersion="3.1" MessageClass="Service" MessageCategory="CardAcquisition" MessageType="Request" ServiceID="4" SaleID="1" POIID="A-POIID"/>
<CardAcquisitionRequest>
<SaleData TokenRequestedType="Customer">
<SaleTransactionID TransactionID="1212203" TimeStamp="2023-10-18T12:12:20+02:00"/>
</SaleData>
<CardAcquisitionTransaction PaymentType="Normal" TotalAmount="0"/>
</CardAcquisitionRequest>
</SaleToPOIRequest>
| Name | Lev | Attribute | Description |
|---|---|---|---|
| CardAcquisitionRequest | 1 | ||
| SaleData | 2 | TokenRequestedType |
Customer only value available and will generate a CNA. |
| SaleTransactionID | 3 | TransactionID | ID of transaction provided by the sale system and may be seen in PosPay reports. Information will not be past to clearing and is not seen in Merchant Portal. |
| TimeStamp | Request timestamp local time with offset from GMT. | ||
| CardAcquisitionTransaction | 2 | PaymentType |
Normal-purchase or Refund. |
| TotalAmount | Normally set to zero. A value may affect behavior for a contactless card. |
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<SaleToPOIResponse>
<MessageHeader MessageClass="Service" MessageCategory="CardAcquisition" MessageType="Response" ServiceID="4" SaleID="1" POIID="A-POIID"/>
<CardAcquisitionResponse>
<Response Result="Success"/>
<SaleData>
<SaleTransactionID TransactionID="1212203" TimeStamp="2023-10-18T12:12:20+02:00"/>
</SaleData>
<POIData>
<POITransactionID TransactionID="8778880092" TimeStamp="2023-10-18T10:12:26.625Z"/>
</POIData>
<PaymentInstrumentData PaymentInstrumentType="Card">
<CardData PaymentBrand="01,Mastercard Debit" MaskedPAN="516815******9659" EntryMode="Contactless">
<PaymentToken TokenRequestedType="Customer" TokenValue="6FD955C23A48A041D881003CDBF836DC59F89CE0ECA8288129696CDF9BB8B8DD67F233"/>
</CardData>
</PaymentInstrumentData>
<LoyaltyAccount LoyaltyBrand="01,Mastercard Debit">
<LoyaltyAccountID EntryMode="Contactless" IdentificationType="ISOTrack2" IdentificationSupport="LoyaltyCard"/>
</LoyaltyAccount>
</CardAcquisitionResponse>
</SaleToPOIResponse>
| Name | Lev | Attribute | Description |
|---|---|---|---|
| CardAcquisitionResponse | 1 | ||
| Response | 2 | Result |
Success or Failure. |
| SaleData | 2 | Echoed from request. | |
| POIData | 2 | ||
| POITransactionID | 3 | TransactionID | ID of transaction set by the terminal. This is seen in PosPay reports as well as on Merchant Portal. The complete element is needed if the transaction needs to be reversed. |
| TimeStamp | Timestamp set by terminal when the transaction is started. Note that the format is UTC. | ||
| PaymentInstrumentData | 2 | PaymentInstrumentType | Values: Card for any transaction made by the terminal with a card or any consumer device. Mobile for an alternative payment instrument made via the terminal. |
| CardData | 3 | PaymentBrand | Comma separated string where the first part is card type. 01-payment card. 02-Combined payment and Loyalty, 03-Loyalty, 04-Neither. May be used instead of 03 for controlling the dialog in the terminal. Second part is the product name. |
| MaskedPAN | |||
| EntryMode |
ICC, Contactless, Magstripe. |
||
| PaymentToken | 4 | TokenRequestedType |
Customer. |
| TokenValue | An irreversible 70 byte hash computed locally in the terminal. A specific card will get the same CNA in all SwedbankPay PAX terminals. | ||
| LoyaltyAccount | 2 | Should only be present for card type 03. |
Proceed after card read
Following a successful CardAcquisitionResponse the terminal will show “Please wait” and any of the messages EnableServiceRequest AbortTransaction, CardAcquisitionRequest, PaymentRequest, DisplayRequest or InputRequest is feasible. If the amount is still not available a DisplayRequest with text set to continue_processing will exit the enabled service state and let the terminal proceed with PIN dialog if appropriate.
Proceed with PIN dialog if appropriate
sequenceDiagram
participant POS
participant Terminal
POS->>Terminal: CardAcquisitionRequest
Terminal->>POS: CardAcquisitionResponse Success
Note left of Terminal: Terminal shows "Please wait"
POS->>Terminal: DisplayRequest "continue_processing"
alt Contactless
Note left of Terminal: Terminal shows "Awaiting amount"
else Chip inserted
Note left of Terminal: Terminal shows "Enter PIN"
end