# Message status (/global/en/docs/Terminal/SystemServices/Message-status)

## 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:

1. 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.

2. 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

```java
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));
            }
        });
```

### 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 |