Event Notification Services

Event Notification Services

The Event Notification Service allows the EPOS application to receive real-time transaction process events from the payment terminal.

By subscribing to this service, the EPOS application can synchronize UI or business logic with the actual transaction state on the payment terminal.

Integration

Register the callback before starting operations whose events you need. Notifications report progress; determine the final business outcome from the corresponding business response.

Use event codes for program logic. For user-facing UI, map them to readable messages in the application's language rather than displaying the abbreviations; logs may retain the original codes.

In the examples below, showEventMessage / ShowEventMessage are application-defined display methods, not SDK APIs. Implement them to display the message on the UI thread.

RetailerManager.setOnEventNotificationCallback((param) -> {
    EventToNotify2Code event = param.getEvent();

    switch (event) {
        case CRDI:
            showEventMessage("Card inserted");
            break;
        case PINE:
            showEventMessage("Please enter your PIN on the terminal");
            break;
        default:
            android.util.Log.d("TerminalEvent", "Unhandled event: " + event);
            break;
    }
});

using PayExplorerConnect;

private static void OnEventToNotify(EventNotificationParam evt)
{
    switch (evt.Event)
    {
        case EventToNotifyCode.CRDI:
            ShowEventMessage("Card inserted");
            break;
        case EventToNotifyCode.PINE:
            ShowEventMessage("Please enter your PIN on the terminal");
            break;
        default:
            System.Diagnostics.Debug.WriteLine("Unhandled terminal event: " + evt.Event);
            break;
    }
}

public static void RegisterEventNotification()
{
    RetailerManager.SetOnEventNotificationCallback(OnEventToNotify);
}

// Implement these methods in an application-owned object that conforms
// to sharedManagerDelegate. Retain the object while events are needed.
- (void)registerTerminalEvents {
    [RetailerManager sharedManager].delegate = self;
}

- (void)onStartOptions {}
- (void)onStartPrint {}
- (void)onStartDisplay:(NSString *)exchangeId sn:(NSString *)sn {}

- (void)onNotification:(EventNotificationParam *)param {
    switch (param.event) {
        case EventToNotifyCodeCRDI:
            [self showEventMessage:@"Card inserted"];
            break;
        case EventToNotifyCodePINE:
            [self showEventMessage:@"Please enter your PIN on the terminal"];
            break;
        default:
            NSLog(@"Unhandled terminal event: %ld", (long)param.event);
            break;
    }
}

Once the callback is registered, it will be triggered whenever the payment terminal reports a transaction-related event.

Receive events in a shared component and dispatch them to the current screen. A later C# registration replaces the process-wide callback; the iOS delegate is weak and must be retained by the application. Marshal UI updates to the platform UI thread and detach screen consumers when they close.

Event Code Values

Event code defines a wide range of terminal and transaction events.
In most integration scenarios, developers only need to handle a subset of these events to provide meaningful transaction feedback.

Below are several key events commonly used during a transaction lifecycle.

Card Interaction

A transaction typically begins with card interaction events.

CDIS indicates that the terminal is waiting for a card to be presented.
CRDI indicates that a card has been inserted or tapped.
CREA indicates that the terminal is reading card data.
CREM indicates that the terminal is waiting for the card to be removed.
CRDR indicates that the card has been removed.

These events are typically used to guide the user through card operations, such as prompting “Present card”, “Reading card”, or “Remove card”.

Cardholder Interaction

During the transaction, the terminal may require input from the cardholder.

PINE indicates that the terminal is waiting for PIN entry.
CSIG indicates that signature collection is in progress.
UCAN indicates that the transaction has been canceled by the user.

These events can be used to update the UI and ensure the user completes required steps.

Transaction Processing

Once cardholder interaction is completed, the transaction enters the processing phase.

ONPR indicates that the transaction is being processed online.
ONAP indicates that the transaction has been approved by the host.
ONDE indicates that the transaction has been declined by the host.
TNOK indicates that the transaction is finally approved at the terminal level.
TNKO indicates that the transaction is finally declined at the terminal level.

These events can be used to display processing status such as “Processing…” or “Authorizing…”.