SwedbankPay.Pax.Sdk 1.3.26259

SwpTrmLib

SDK for using Swedbank Pay terminals. Implements the Nexo Retailer v3.1 as used by Swedbank Pay. For complete documentation please visit developer.Swedbankpay.com/pax-terminals/NET/.

Create an instance

Contains at the moment only one implementation through class PAXTrmImp_1. Its static create method returns an instance of interface ISwpTrmIf_1. Provided that the current object implements the ISwpTrmCallbackInterface, the following creates an instance to an object with ISwpTrmIf_1 interface.

ISwpTrmIf_1 Pax = PAXTrmImp_1.Create(new SwpIfConfig(), this);

The ISwpTrmCallbackInterface

As of now it both exposes events and requires an interface to callbacks, ISwpTrmCallbackInterface. If the events are not subscribed for they all appear in the callback EventCallback. This is useful if using more than one terminal which requires one instance per terminal.

public interface ISwpTrmCallbackInterface
{
    void ConfirmationHandler(string text, IConfirmationResult callback);

    void EventNotificationHandler(EventToNotifyEnumeration type, string text);

    void SyncRequestResult(object result);

    void EventCallback(EventCallbackObject eventObject);
}

ConfirmationHandler

This callback occurs when the terminal wants a confirmation from the POS operator. Typically an approval of a customer signature on a signature receipt.

EventNotificationHandler

Occurs when an event notification message is received from the terminal. Typically CardInserted, CardRemoved, MaintenanceRequired etc.

SyncRequestResult

Occurs when a synchronous method call has ended up with a result/response. A call to the method Payment will eventually give a Payment result with receipt information.

Example of how to use the SycnRequestResult Callback

public void SyncRequestResult(object result)
    {
        switch (Enum.Parse(typeof(RequestResultTypes), result.GetType().Name)) {
            case RequestResultTypes.OpenResult:
                ...
                break;
            case RequestResultTypes.PaymentRequestResult:
                ...
                break;
                ...

EventCallback

Occurs when an ISwpTrmIf_1 event has not been subscribed for. Typically a display message from the terminal that may be displayed on the POS to inform the operator what is going on on the terminal.

Example of how to use the EventCallback method

public void EventCallback(EventCallbackObject eventObject)
{

    switch (eventObject.type)
    {
        case EventCallbackTypes.TerminalAddressObtainedEventCallback:
            ...
            break;
        case EventCallbackTypes.NewStatusEventCallback:
            ...
            break;
        case EventCallbackTypes.DisplayEventCallback:
            ...
            break;
        case EventCallbackTypes.PrintRequestEventCallback:
            ...
            break;
        ...

Asynchronous or Synchronous methods

The ISwpTrmIf_1 has implementation for both asynchronous and synchronous methods. Note, that the synchronous methods ends up in the asynchronous methods and the SyncRequestResult callback will give the same result object as the awaitable method.

Get going to actually make a payment

Once an instance is created call the Start method with a SaleApplInfo object. The SaleApplInfo holds essential information. POIID among others.

POIID

POIID is an identification of the Point of Interaction and decides what parameters to fetch from the TMS. The POIID must be registered in the TMS and may be decided by the customer/partner or Swedbank Pay. It could be any kind of unique identification within an organisation.

SaleCapabilities

SaleCapabilities is used in the LoginRequest message to the terminal and decides whether the terminal should send requests towards the Sale System or not, i.e. if the sale system needs to have a listener or not. Default is that a listener is used, but if string SaleCapabilities only contains PrinterReceipt, a listener will not be started. In that case it is not possible to do transactions approved with signature. The SwpIfConfig in call to .Create sets which port to listen on. Default is port 11000.

Set Terminal address and port

Before communicating with the terminal the created instance needs the address and port for the terminal. Set the property TerminalAddress using the following format <ip-address>:<port>. Note, that if a listener has been started the terminal address and port may be initialized from the terminal's admin menu by entering ECR IP and ECR Port. A configuration message is then sent from the terminal. This enables a terminal to be installed without having to login to the sale system. When the configuration message is received the OnTerminalAddressObtained will occur or the EventCallback is called.

Steps to make a transaction

• Call Open/OpenAsync to send a LoginRequest to the terminal and wait for answer. On success it is possible to start using the terminal. The Login session, as it is called, last until Close method is called or another call to Open/OpenAsync is made.
• Call Payment/PaymentAsync or Refund/RefundAsync to start a transaction and wait for response.
• Call GetPaymentInstrumetAsync to start a transaction when a card needs to be read before the amount is known. Follow up with call to either Payment/PaymentAsynch or Refund/RefundAsynch when a card has been read.

Call Close to send logout. Do this at least once a day to let the terminal update its parameters.

Payment results

All results that contain receipt data are formatted automatically by ReceiptFormatter before giving the result to the caller (consumer of the instance).

Brief method description in relevant order.

Start

Call Start to initialize the instance with a SaleApplInfo object. First call to be made after creation.

Open/OpenAsync

First method to call that actually sends a message to the terminal and makes it ready to be used.

GetPaymentInstrument/GetPaymentInstrumentAsync

This method will start a transaction for wich a card needs to be read before the amount is known. The result after a card read will hold information about the card, but not a full card number. It will always give a CNA - Card Number Alias - that may be used to identify the card in a loyalty system.

Continue/ContinueAsync

Only relevant if a chip card has been read and PIN entry should be possible before amount is known.

Payment/PaymentAsync

Call this method when amount is known and a payment shall be made. This will open the terminal's card readers unless GetPaymentInstrument/GetPaymentInstrumentAsync was used prior to this call.

Refund/RefundAsync

Call this method when amount is known and a refund shall be made. This will open the terminal's card readers unless GetPaymentInstrument/GetPaymentInstrumentAsync was used prior to this call.

Abort/AbortAsync

Aborts any ongoing request, GetPaymentInstrument, Payment, Refund. The actual request that is aborted will render a result.

ReversLast/ReversLastAsync

Reverses the last transaction if it was successful.

GetLastTransactionResult/GetLastTransactionResultAsync

Gets the last transaction result including receipt data. This is useful if the sale system for some reason is unable to pick up the original result.

RequestCustomerConfirmation/RequestCustomerConfirmationAsync

Possibility to ask the customer a Yes/No question to be answered on the terminal. The response will contain a boolean, true/false. This method is valid before call to any of Payment or Refund or after the result of those methods.

RequestCustomerDigitString/RequestCustomerDigitStringAsync

Possibility to ask the customer for a digit string. Eg. Cell phone number. This method is valid before call to any of Payment or Refund or after the result of those methods.

RequestToDisplay/RequestToDisplayAsync

Possibility to display a message on the terminal. The message will stay visible until next request is made. This method is valid before call to any of Payment or Refund or after the result of those methods.

Close

Ends the login session by sending a LogoutRequest to the terminal. By default MaintenanceAllowed flag in LogoutRequest will be set to true, making it possible for the terminal to update its parameters. It is however possible to pass the parameter as false in the call to inhibit updates.

Stop

Stops the listener if started.