Użycie terminala płatniczego CELTO S1 w aplikacjach sprzedaży

1              Wstęp              3

2              Sposób użycia              3

3              Interfejsy              5

3.1              IOEFTTerminal              5

3.2              IOICFPEFTAuthorization              6

4              Typy wyliczeniowe              7

4.1              OICEFTTTransactionStatus              7

4.2              OICEFTTTransactionAttr              8

5              Przykłady              8

5.1              Funkcja Authorize              8

5.2              Funkcja Finalize              9

5.3              Funkcje wykorzystywane w funkcjach Authorize i Finalize              10

6              Zakończenie              12

1           Wstęp

Software’owy terminal płatniczy (nazywany dalej Celto S1) jest programem, który funkcjonalnie odpowiada terminalom płatniczym dostępnym na rynku. Umożliwia on autoryzowanie transakcji dokonywanych za pośrednictwem kart płatniczych. Do poprawnego działania wymaga systemu Windows, drukarki fiskalnej wyprodukowanej przez firmę NOVITUS SA, pinpad’a oraz modemu. Drukarka oraz pinpad muszą być podłączone do portów szeregowych lub za pomocą konwerterów RS232/USB do gniazd USB komputera, na którym uruchomiony jest Celto S1. Terminal może działać jako aplikacja samodzielna, ale ponieważ jest również obiektem automatyzacji może być uruchamiany przez program sprzedaży działający na tym samym komputerze (musi być to program windows’owy) a następnie może wymieniać dane z tym programem. Tej właśnie tematyce poświęcony jest poniższy tekst.

Podczas instalacji terminala Celto S1 następuje skopiowanie i zarejestrowanie w systemie programu terminala oraz wszystkich bibliotek, z których on korzysta. W związku z tym po instalacji Celto S1 system ma dostęp do wszystkich interfejsów COM opisanych w tym tekście.

2           Sposób użycia

Aplikacja sprzedaży działa bez zmian do momentu zamknięcia paragonu fiskalnego. Konieczność zmiany sposobu jej działania pojawia się w momencie, gdy klient deklaruje chęć zapłacenia kartą. W takim przypadku jeszcze przed zamknięciem paragonu na drukarce fiskalnej należy utworzyć obiekt Celto S1. Powoduje to uruchomienie aplikacji terminala. W Delphi wygląda to następująco:

Terminal := CreateCOMObject(Class_OEFTTerminal) as IOEFTTerminal;

Kolejnym krokiem jest utworzenie struktury służącej do gromadzenia danych o przeprowadzanej transakcji:

Authorization := CreateCOMObject(Class_OICFPEFTAuthorization) as IOICFPEFTAuthorization;

Następnie wypełnić należy następujące pola struktury:

Authorization.POSId := < Identyfikator stanowiska kasowego >

Authorization.POSOperatorID := < Identyfikator kasjera >

Authorization.POSDocRefNo := < Numer paragonu >

Authorization.TransMode := 'P';

Authorization.Amount := < Kwota transakcji wyrażona w groszach >

Wszystkie dane są tekstami. Po ich wprowadzeniu wywołać należy funkcję StartTransaction obiektu Terminal, której parametrem jest wskaźnik do w/w struktury:

Terminal.StartTransaction(Authorization);

Zwraca ona wartość True, w przypadku powodzenia. Jeżeli zwróconą wartością jest False, należy sprawdzić wartość pola Authorization.ErrorCode i jeżeli jest równa AXERR_STARTUP można ponawiać wywołanie aż do uzyskania sukcesu lub upłynięcia założonego timeout’u. Gdy wartość jest inna, oznacza ona brak możliwości przeprowadzenia autoryzacji transakcji realizowaną kartą płatniczą.

Jeżeli rozpoczęcie transakcji się powiedzie rozpoczyna się dialog z terminalem. Aplikacja sprzedaży może odpytywać terminal o bieżący stan transakcji za pomocą funkcji:

Terminal.GetTransactionState(Authorization);

Gdy funkcja ta zwróci wartość True, to można sprawdzić stan transakcji. Zawiera go pole:

Authorization.TransactionStatus

i może ono przyjmować wartości:

oefttsNotReady,

oefttsIdle,

oefttsBusy,

oefttsNotInitialized,

oefttsStarted,

oefttsWaitingForCard,

oefttsWaitingForCardConfirmation,

oefttsWaitingForServerID,

oefttsWaitingForPassword,

oefttsWaitingForAmount,

oefttsWaitingForPrevAmount,

oefttsWaitingForPrevAuthCode,

oefttsWaitingForPIN,

oefttsContactingAuthHost,

oefttsContactingAuthHost2,

oefttsContactingAuthHost3,

oefttsVoiceAuth,

oefttsCheckingSign,

oefttsCheckingIdentity,

oefttsPrintingAccepted,

oefttsPrintingCopy,

oefttsPrintingRejected,

oefttsFinished,

oefttsError,

oefttsWaitingForVoid,

oefttsPrintingVoid

Korzystając z tych wartości można na bieżąco informować Użytkownika o stanie transakcji. Jeżeli zwrócone zostaną stany oefttsPrintingRejected lub oefttsError należy odczytać kod błędu z pola:

Authorization.TransactionErrorCode

Autoryzację należy uznać za zakończoną sukcesem w przypadku, gdy pole Authorization.TransactionStatus przyjmie wartość oefttsPrintingAccepted .

Całe powyższe postępowanie można zamknąć w jednej funkcji (nazwijmy ją Authorize) zwracającej wartość True, gdy autoryzacja powiedzie się i False w przeciwnym wypadku. Może ona wyglądać podobnie, jak zaprezentowana w przykładach funkcja Authorize.

Gdy w/w funkcja Authorize zwróci wartość True, to należy sprawdzić, czy w polu Authorization.TransactionAttrs ustawiona jest flaga bitowa oefttaPrinterNeeded. Jeżeli tak jest, to należy zamknąć paragon i sfinalizować transakcję drukując na drukarce fiskalnej potwierdzenie transakcji płatniczej. Wcześniej należy zamknąć port drukarki fiskalnej, aby Celto S1 mógł uzyskać do niej dostęp.

Pierwszą czynnością, którą należy wykonać podczas finalizacji transakcji jest wywołanie funkcji Terminal.YieldPrinter informującej terminal, że może rozpocząć drukowanie. Gdy funkcja ta zwróci True, można podobnie jak miało to miejsce w funkcji Authorize odpytywać terminal o bieżący stan finalizacji za pomocą funkcji

Terminal.GetTransactionState(Authorization);

Jeżeli zwrócony zostanie stan oefttsError należy odczytać kod błędu z pola:

Authorization.TransactionErrorCode

Finalizacja kończy się sukcesem w przypadku, gdy pole:

Authorization.TransactionStatus

przyjmie wartość:

oefttsFinished.

Podobnie jak w przypadku funkcji Authorize, również finalizacja może zostać zamknięta w jednej funkcji (Finalize). Kod źródłowy takiej funkcji zawiera przykład funkcja Finalize.

Jeżeli funkcja Authorize zwróci wartość False (autoryzacja nie powiodła się), to również należy sprawdzić czy w polu Authorization.TransactionAttrs ustawiona jest flaga bitowa oefttaPrinterNeeded. Jeżeli nie, to można pozostawić otwarty paragon fiskalny i przejść do ponownego ustalania form płatności. Jednakże, gdy terminal żąda drukarki, konieczne jest udostępnienie mu jej. W takim przypadku należy anulować otwarty paragon, zamknąć port drukarki fiskalnej i wywołać funkcję

Finalize(Authorization)

Po zakończeniu autoryzacji aplikacja sprzedaży może kontynuować działanie, otwierając port drukarki fiskalnej i drukując kolejny paragon.

3           Interfejsy

Terminal Celto S1 oraz biblioteki, z których korzysta implementują wiele interfejsów COM, z których mogą korzystać programiści integrujący terminal ze swoimi aplikacjami sprzedaży. W praktyce przydatne są jedynie te opisane poniżej.

3.1          IOEFTTerminal

  Metody:

    function StartTransaction (const AuthData: IOICFPEFTAuthorization): WordBool;

      Opis:

        Funkcja służąca do rozpoczęcia transakcji kartą.

      Parametry:

      Zwracana wartość:

        TRUE jeżeli nie wystąpił błąd, w przeciwnym wypadku FALSE.

    function GetTransactionState (const AuthData: IOICFPEFTAuthorization): WordBool;

      Opis:

        Funkcja służąca do odpytania terminala o bieżący stan transakcji.

      Parametry:

      Zwracana wartość:

        TRUE jeżeli nie wystąpił błąd, w przeciwnym wypadku FALSE.

    function YieldPrinter (const Printer: IOICFiscalPrinter): WordBool;

      Opis:

        Funkcja służąca do przekazania terminalowi sterowania drukarką fiskalną.

      Parametry: