API reference DisplayParam Object
The SDK provides interfaces to push order details (such as item lists and total amount) to the payment terminal for display, improving the overall user experience.
This is typically achieved by calling the Display API, and the data format must comply with the terminal requirements.
The Display Request allows you to present content on the payment terminal screen outside of the payment flow.
You can use this feature to:
ActionMessageParam displayContentParam = ActionMessageParam.newBuilder()
.format(OutputFormat3Code.SREF)
.messageContent("{\"refId\":\"shoppingCart\",\"data\":{\"received\":\"$1.00\",\"discount\":\"$2.00\",\"change\":\"$0.00\",\"actualHarvest\":\"$1.00\",\"details\":[{\"number\":\"1\",\"name\":\"Strawberry Cheese Cake\",\"price\":\"$1.00\",\"qty\":\"1\",\"subTotal\":\"$1.00\"},{\"number\":\"2\",\"name\":\"Chocolate Mousse Cake\",\"price\":\"$1.00\",\"qty\":\"1\",\"subTotal\":\"$1.00\"}]}}")
.messageDestination(UserInterface4Code.MDSP) //Merchant display
.minimumDisplayTime(15L) // 15 seconds
.responseRequiredFlag(true)
.build();
DisplayParam displayParam = DisplayParam.newBuilder()
.addDisplayContent(displayContentParam)
.build();
RetailerManager.getInstance()
.provideDeviceService()
.newDisplayExchange(displayParam)
.startAsyncExchange(new Exchange.RetailerSDKCallback<DisplayResult>() {
@Override
public void onError(int code, String msg) {
Log.e(TAG, "failed: " + code + ", " + msg);
}
@Override
public void onResult(DisplayResult result) {
Log.i(TAG, "result: " + GsonUtils.toJson(result));
}
});using System;
using PayExplorerConnect;
public void HandleDisplayError(int code, string message)
{
Console.WriteLine($"Error: {code}, Message: {message}");
}
public void HandleDisplayResult(DisplayResult result)
{
Console.WriteLine($"Response: {result.Response}");
}
public string StartDisplay()
{
// Replace the sample cart data and display settings for your scenario.
string shoppingCartContent =
"{\"refId\":\"shoppingCart\",\"data\":{\"received\":\"$1.00\"," +
"\"discount\":\"$2.00\"," +
"\"change\":\"$0.00\"," +
"\"actualHarvest\":\"$1.00\"," +
"\"details\":[{\"number\":\"1\",\"name\":\"Strawberry Cheese Cake\",\"price\":\"$1.00\"," +
"\"qty\":\"1\"," +
"\"subTotal\":\"$1.00\"}," +
"{\"number\":\"2\",\"name\":\"Chocolate Mousse Cake\",\"price\":\"$1.00\"," +
"\"qty\":\"1\"," +
"\"subTotal\":\"$1.00\"}]}}";
ActionMessageParam content = new ActionMessageParam.Builder()
.Format(OutputFormatCode.SREF)
.MessageContent(shoppingCartContent)
.MessageDestination(ReceiptOutputTarget.MDSP) //Merchant display
.MinimumDisplayTime(15) // 15 seconds
.ResponseRequiredFlag(true)
.Build();
DisplayParam param = new DisplayParam.Builder()
.AddDisplayContent(content)
.Build();
string exchangeId = RetailerManager
.ProvideDeviceService()
.NewDisplayExchange(param)
.StartAsyncExchange(HandleDisplayResult, HandleDisplayError);
return exchangeId;
}#import <PayExplorerConnect/RetailerManager.h>
#import <PayExplorerConnect/DisplayParam+Builder.h>
ActionMessageParam *messageParam = [ActionMessageParam makeWithBuilder:^(ActionMessageParamBuilder *builder) {
builder.format(OutputFormatCodeSREF);
builder.informationQualifier(InformationQualifyCodeDISP);
builder.messageContent(@"{\"refId\":\"shoppingCart\",\"data\":{\"received\":\"$1.00\",\"discount\":\"$2.00\",\"change\":\"$0.00\",\"actualHarvest\":\"$1.00\",\"details\":[{\"number\":\"1\",\"name\":\"Strawberry Cheese Cake\",\"price\":\"$1.00\",\"qty\":\"1\",\"subTotal\":\"$1.00\"},{\"number\":\"2\",\"name\":\"Chocolate Mousse Cake\",\"price\":\"$1.00\",\"qty\":\"1\",\"subTotal\":\"$1.00\"}]}}");
builder.messageDestination(ReceiptOutputTargetMDSP);
builder.responseRequiredFlag(@"true");
}];
DisplayParam *params = [DisplayParam makeWithBuilder:^(DisplayParamBuilder *builder) {
builder.addDisplayContent(messageParam);
}];
[[RetailerManager sharedManager] display:params block:^(NSString *exchangeId) {
// Save the exchange ID to track this request.
} result:^(id result, NSInteger errcode, NSString *msg) {
if (errcode != 0 && result == nil) {
// Handle request error.
return;
}
DisplayResult *displayResult = (DisplayResult *)result;
// Handle display result.
}];A successful Display callback confirms that the display request was processed; the content remains on the terminal screen. Retain its exchange ID after the callback. When updating Display repeatedly, keep the latest Display exchange ID for each terminal.
If Display content is still shown, before starting an operation that presents its own terminal UI, such as a financial operation or NFC Tag, pass that terminal's latest Display exchange ID as AbortParam.orgExchangeIdentification and call Abort. Start the next operation after Abort succeeds.
Operations without a terminal UI, such as Print and Transmit, and further Display updates do not require aborting the previous Display.
To ensure a smooth user experience, follow this recommended interaction flow:
Clearly separating responsibilities between the EPOS and the payment terminal helps ensure a clean integration design:
EPOS Responsibilities
Payment Terminal Responsibilities