PEP DOCS

Route payments to multiple payment service providers

In real deployment environments, a payment terminal may provide multiple services of the same type, or multiple payment terminals may be available around an EPOS.

Before initiating a transaction, EPOS may need to select an appropriate service object as the target.

Service Object Description

A service object represents a specific callable capability provided by a payment terminal, for example:

Purchase Service: Card payment transactions
Refund Service: Refund processing
Printer Service: Receipt printing

A single terminal may expose multiple service objects of the same type. This can happen in the following cases:

Multiple payment applications The same terminal has multiple payment applications installed that support the same transaction type.
Multiple service instances A single payment application exposes multiple service instances with different configurations.

Therefore, before initiating a transaction, EPOS may need to:

Retrieve the list of available service objects on the target device.
Select a service object based on business rules.

Retrieve Service Objects from a Device

EPOS can retrieve discovered services through the SDK, then filter them by the target terminal and required capability:

RetailerSettingManager.showAllService((List<TerminalServiceInfo> terminalServiceInfos)->{
    for (TerminalServiceInfo terminalServiceInfo : terminalServiceInfos) {
        System.out.println(terminalServiceInfo.getServiceId());
    }
});

RetailerSettingManager.ShowAllService(services =>
{
    foreach (var service in services)
    {
        Console.WriteLine(service.ServiceId);
    }
});

NSArray<ServiceInfo *> *serviceArray = [[RetailerSettingManager sharedManager] showAllService];
    for (ServiceInfo *info in serviceArray) {
        NSLog(@"terminal SN = %@",info.deviceSn);
        NSLog(@"serviceId = %@",info.serviceId);
}

Service information includes terminal identity, service type, service ID, names, and application information. Android and Windows use TerminalServiceInfo; iOS uses ServiceInfo.

Information	Purpose
Terminal SN	Identify the terminal hosting the service.
Service type	Identify the capability; several providers may offer the same type.
Service ID	Identify a specific service instance; combine it with terminal SN when selecting a provider on a particular terminal.

Filter by terminal and capability before selecting a provider. Before setting a default or per-request target by SN or service ID, the SDK must have discovered the corresponding terminal or service. Obtain service IDs from discovery results. Service type, service ID, and terminal SN are not interchangeable.

Target Configuration Scope

Configuration	Effect
Default target in the setting manager	Supply a reusable target for subsequent requests without an explicit per-request target.
Target on an individual request	Specify the terminal or service for that request, without temporarily changing a shared default to route it.
SDK selection and remember options	Choose from available services according to the selection policy; the picker may appear when there is no applicable target.

Communication, saved settings, and terminal switching are covered in the terminal configuration guide. Service routing remains subject to the capabilities actually offered by the selected provider.

Default Target Configuration

For a terminal's SN, address, and communication configuration, see Terminal Configuration and Selection. When that terminal has multiple providers, set the terminal SN and service ID together.

Set a service provider on the selected terminal for applicable requests:

// Set the selected terminal and provider as the default target.
RetailerSettingManager.destination(Destinations.serviceDestination("serviceId","SN"));

// Replace the sample service ID and SN with your target service and terminal.
RetailerSettingManager.Destination(Destinations.ServiceDestination("serviceId", "SN"));

[[RetailerSettingManager sharedManager] destination:@"SN" serviceId:@"serviceId"];

Recommendations for Multi-Device and Multi-Service Scenarios

In the following scenarios, it is NOT recommended to bind to a fixed service object:

Multiple terminals are available around the EPOS
Terminals may be replaced or moved dynamically
Different transaction types require different devices or services

In such cases, it is recommended to:

Use SDK-based device and service discovery
Display available devices and services via UI
Let the operator select the target service at runtime

Dynamic Target Selection

A request target applies to the individual operation. Select it from discovery results, and retain the terminal and service identity used by that request for later queries or related operations.

Specify Target Device

// Specify the target terminal by SN
RetailerManager.provideFinancialService()
        .newPaymentExchange(paymentParam)
        .destination(Destinations.terminal("NDNL00017998"))
        .startAsyncExchange(callback);

// Specify the local terminal to execute the transaction
RetailerManager.provideFinancialService()
        .newPaymentExchange(paymentParam)
        .destination(Destinations.currentTerminal())
        .startAsyncExchange(callback);

using PayExplorerConnect;

public void HandlePaymentError(int code, string message)
{
    // Called when a non-transaction request error occurs
}

public void HandlePaymentResult(PaymentResult result)
{
    // Handle payment result.
}

public string StartPaymentOnTerminal()
{
    // Replace the transaction values and terminal SN for your scenario.
    PaymentParam paymentParam = new PaymentParam.Builder()
        .TransactionReference("500001")
        .TotalAmount("99.99")
        .Build();

    return RetailerManager
        .ProvideFinancialService()
        .NewPaymentExchange(paymentParam)
        .Destination(Destinations.Terminal("NDNL00017998"))
        .StartAsyncExchange(HandlePaymentResult, HandlePaymentError);
}

// paymentParam is prepared as described in the payment guide.
DestinationParams *target = [[DestinationParams alloc] init];
target.sn = @"NL00000001";
paymentParam.servicesParams = target;

Specify Both Device and Service

This scenario applies when there are multiple acquirers and multiple devices, but you want a specific transaction to prioritize a specific acquirer service on a specific device.

RetailerManager.provideFinancialService().newPaymentExchange(paymentParam)
       .destination(Destinations.serviceDestination("serviceId", "SN"))
       .startAsyncExchange(callback);

// Reuse the same payment result and error handlers.
public string StartPaymentOnService()
{
    // Replace the transaction values, service ID, and terminal SN for your scenario.
    PaymentParam paymentParam = new PaymentParam.Builder()
        .TransactionReference("500002")
        .TotalAmount("99.99")
        .Build();

    return RetailerManager
        .ProvideFinancialService()
        .NewPaymentExchange(paymentParam)
        .Destination(Destinations.ServiceDestination("serviceId", "SN"))
        .StartAsyncExchange(HandlePaymentResult, HandlePaymentError);
}

// Use the terminal SN and service ID selected from discovery results.
DestinationParams *target = [[DestinationParams alloc] init];
target.sn = @"SN";
target.serviceId = @"serviceId";
paymentParam.servicesParams = target;

Clear Configuration and Reset Strategy

When terminals or services change, clear the scope affected by the obsolete choice: terminal, service type, service category, or all options. Available overloads and scopes differ by platform. Update the application's saved target as well; see Terminal Configuration and Selection for switching and restoration.

// Clear the preferred device configuration (by SN)
RetailerSettingManager.clearRememberOption("sn");

// Clear the configuration for a specific service
RetailerSettingManager.clearRememberOption(ServiceTypes.CARD_PAYMENT);

// Clear the configuration for a specific service category
RetailerSettingManager.clearRememberOption(ServiceCategory.FINANCIAL);

// Clear all saved configuration
RetailerSettingManager.clearRememberOption(ServiceTypes.ALL);

// Clear the configuration for a specific service category
RetailerSettingManager.ClearRememberOptions(ServiceCategory.FINANCIAL);
// Clear the configuration for a specific service
RetailerSettingManager.ClearRememberOptions(ServiceTypes.CARD_PAYMENT);
// Clear the preferred device configuration (by SN)
RetailerSettingManager.ClearRememberOptions("sn");

-(void)clearOptionWithSn:(NSString*)sn;
-(void)clearOptionWithService;
-(void)clearOptionWithCategory;
-(void)clearAllOption;