PEP DOCS

Message Status

During a transaction, communication or technical issues may prevent the POS app from receiving a response, making it unclear to cashiers whether the transaction was successful. As a result, they may attempt to cancel, refund, or repeat the transaction. To prevent cashiers from taking incorrect actions, the POS app integration should support transaction status inquiries. By checking the transaction status, the system can determine if the transaction has been processed (along with the original transaction response), is still in progress, or was not found.

Usage Scenarios

The Message Status API can be used in two primary scenarios:

Querying Past Transactions
When no transaction is currently in progress, this API can be used to look up the result of a previously completed transaction. Developers may use this scenario, for example:

To reconcile payment results in case the original response was lost or not received in time.
To verify the final status of a transaction for reporting or settlement purposes.

Monitoring an Ongoing Transaction
During an active transaction, the API can be called to check the execution progress in real time through the processStatus field.
This allows the client to:

Track intermediate states such as card discovery, PIN entry, or online processing.
Provide better user feedback by displaying the current stage of the payment process.
Decide whether to continue waiting or to handle timeouts or user cancellations appropriately.

Sample Code

MessageStatusParam param = MessageStatusParam.newBuilder()
        .orgExchangeIdentification("000000001")
        .initiatingPartyIdentification("Cashier1")
        .build();
RetailerManager.provideSystemService()
        .newMessageStatusExchange(param)
        .startAsyncExchange(new Exchange.RetailerSDKCallback<MessageStatusResult>() {
            @Override
            public void onError(int code, String msg) {
                Log.e(TAG, "failed: " + code + ", " + msg);
            }
            @Override
            public void onResult(MessageStatusResult result) {
                Log.i(TAG, "result: " + GsonUtils.toJson(result));
            }
        });

using System;
using PayExplorerConnect;

public void HandleMessageStatusError(int code, string message)
{
    Console.WriteLine($"Error: {code}, Message: {message}");
}

public void HandleMessageStatusResult(MessageStatusResult result)
{
    Console.WriteLine($"Query response: {result.Response}");
}

public string StartMessageStatus()
{
    // Replace the sample ID with the exchange ID of the request to query.
    MessageStatusParam param = new MessageStatusParam.Builder()
        .OrgExchangeIdentification("000000001")
        .InitiatingPartyIdentification("Cashier1")
        .Build();

    string exchangeId = RetailerManager
        .ProvideSystemService()
        .NewMessageStatusExchange(param)
        .StartAsyncExchange(
            HandleMessageStatusResult,
            HandleMessageStatusError);

    return exchangeId;
}

#import <PayExplorerConnect/RetailerManager.h>
#import <PayExplorerConnect/MessageStatusParam+Builder.h>

// Use the exchange ID saved when the original request started.
MessageStatusParam *params = [MessageStatusParam makeWithBuilder:^(MessageStatusParamBuilder *builder) {
    builder.orgExchangeIdentification(@"000000001");
    builder.initiatingPartyIdentification(@"Cashier1");
}];

[[RetailerManager sharedManager] messageStatus: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;
    }
    MessageStatusResult *statusResult = (MessageStatusResult *)result;
    // Handle message status result.
}];

MessageStatusParam

Parameter	Required	Type	Description
orgTransactionReference	✔	Max35Text	Global reference of the original transaction for the sale system.

MessageStatusResult

Parameter	Required	Type	Description
recipientPartyIdentification	✔	Max35Text	Unique identification of the partner that is the recipient of the message exchange.
response	✔	CodeSet	Result of the requested transaction.
responseReason		CodeSet	Detail of the response.
additionalResponseInformation		Max140Text	Additional information to be logged for further examination.
If response=SUCC, the optional params below will be mandatory.
orgExchangeIdentification	✔	Max35Text	Identification of the requested previous message.
initiatingPartyIdentification	✔	Max35Text	Identification of Initiating Party.
paymentResult		Object	Result of original payment transaction. If the original transaction is payment, this field is mandatory.
reversalResult		Object	Result of original reversal transaction. If the original transaction is reversal, this field is mandatory.
refundResult		Object	Result of original refund transaction. If the original transaction is refund, this field is mandatory.
preAuthResult		Object	Result of original pre-auth transaction. If the original transaction is pre-auth, this field is mandatory.
authAdjustmentResult		Object	Result of original auth adjustment transaction. If the original transaction is auth adjustment, this field is mandatory.
processStatus		CodeSet	Indicates the current execution status of the transaction process, not the final result. CDIS CARD_DISCOVERY – Waiting for card to be presented or detected ASEL APP_SELECTION – Selecting application (AID) CREA CARD_READ – Reading card data CREM CARD_REMOVAL – Waiting for card removal UCAN USER_CANCELED – Transaction canceled by user ONPR ONLINE_PROCESSING – Transaction is being processed online ONAP ONLINE_APPROVED – Transaction approved by host ONDE ONLINE_DECLINED – Transaction declined by host CSIG COLLECTING_SIGNATURE – Collecting signature MCAE MANUAL_CARD_ENTRY_ACTIVATED – Manual card entry mode activated PINE PIN_ENTRY – Waiting for PIN entry

Message status