Recover a payment

Outlines recovering the final status of a payment when you don't receive a payment response.


TransactionStatusRequest is an error recovery mechanism. If the response to a payment request does not arrive within 120 seconds you can retrieve the final status of the transaction.

Endpoint

The URL used to send  Terminal API  messages depends on your type of implementation. For more information on the architectures available, see the Terminal API Overview .

Request

The SaleID and ServiceID in the MessageHeader should be unique. SaleID and ServiceID combinations are rejected if used recently, within 48 hours.

For a list of Transaction Status Request fields, see TransactionStatusRequest fields.

TransactionStatusRequest
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "MessageClass": "Service",
      "MessageCategory": "TransactionStatus",
      "MessageType": "Request",
      "ServiceID": "29235",
      "SaleID": "POSSystemID12345",
      "POIID": "MX925-289173817"
    },
    "TransactionStatusRequest": {
      "MessageReference": {
        "MessageCategory": "Payment",
        "SaleID": "POSSystemID12345",
	"ServiceID": "2345"
      }
    }
  }
}

Status request on the reversal with ServiceID "2345" originally done with SaleID "POSSystemID12345".

If receipts are to be included in the response, the TransactionStatusRequest part of the request looks like:

TransactionStatusRequest with Receipts
 "TransactionStatusRequest" : {
         "DocumentQualifier" : [
            "CashierReceipt",
            "CustomerReceipt"
         ],
         "ReceiptReprintFlag" : true
      }

You can request the status of a PaymentRequestReversalRequest or StoredValueRequest. If you specify no MesageCategory, you get the most recent result corresponding to any of the of the above request types.

The ServiceID and SaleID in the MessageHeader refer to the transaction status request, whereas the ServiceID and SaleID in the MessageReference refer to the original request.

Response

For a list of Transaction Status Response fields, see TransactionStatusResponse fields.

You receive a response with the following fields:

{
   "SaleToPOIResponse" : {
      "MessageHeader" : {
         "ServiceID" : "29235",
         "MessageCategory" : "TransactionStatus",
         "ProtocolVersion" : "3.0",
         "MessageType" : "Response",
         "SaleID" : "POSSystemID12345",
         "POIID" : "MX925-260193322",
         "MessageClass" : "Service"
      },
      "TransactionStatusResponse" : {
         "Response" : {
            "Result" : "Success"
         },
         "RepeatedMessageResponse" : {
            "MessageHeader" : {
               "MessageCategory" : "Payment",
               "ServiceID" : "2345",
               "ProtocolVersion" : "3.0",
               "MessageType" : "Response",
               "POIID" : "MX925-260193322",
               "MessageClass" : "Service",
               "SaleID" : "POSSystemID12345"
            },
            "RepeatedResponseMessageBody" : {
               "PaymentResponse" : {
                  "PaymentResult" : {
                     "PaymentInstrumentData" : {
                        "CardData" : {
                           "EntryMode" : []
                        },
                        "PaymentInstrumentType" : "Card"
                     },
                     "PaymentAcquirerData" : {
                        "AcquirerPOIID" : "MX925-260193322",
                        "MerchantID" : "TestMerchantPOS"
                     }
                  },
                  "POIData" : {
                     "POITransactionID" : {
                        "TimeStamp" : "2017-08-22T11:00:23.000Z",
                        "TransactionID" : "oLkO001503399623002"
                     }
                  },
                  "Response" : {
                     "AdditionalResponse" : "104 Merchant cancelled tx",
                     "ErrorCondition" : "Aborted",
                     "Result" : "Failure"
                  },
                  "SaleData" : {
                     "SaleTransactionID" : {
                        "TransactionID" : "17481",
                        "TimeStamp" : "2017-08-22T11:00:34.000Z"
                     },
                     "TokenRequestedType" : "Customer"
                  }
               }
            }
         }
      }
   }
}
{
   "SaleToPOIResponse" : {
      "MessageHeader" : {
         "POIID" : "MX925-123456789",
         "SaleID" : "POSSystemID12345",
         "ServiceID" : "0207111140",
         "ProtocolVersion" : "3.0",
         "MessageCategory" : "TransactionStatus",
         "MessageType" : "Response",
         "MessageClass" : "Service"
      },
      "TransactionStatusResponse" : {
         "Response" : {
            "ErrorCondition" : "NotFound",
            "Result" : "Failure",
            "AdditionalResponse" : "Message not Found, last PaymentRequest has ID 2"
         }
      }
   }
}
{
   "SaleToPOIResponse" : {
      "MessageHeader" : {
         "MessageType" : "Response",
         "MessageCategory" : "TransactionStatus",
         "MessageClass" : "Service",
         "ProtocolVersion" : "3.0",
         "POIID" : "MX925-260193322",
         "SaleID" : "POSSystemID12345",
         "ServiceID" : "0207111140"
      },
      "TransactionStatusResponse" : {
         "Response" : {
            "Result" : "Failure",
            "ErrorCondition" : "InProgress",
            "AdditionalResponse" : "Uncompleted transaction"
         }
      }
   }
}
{
   "SaleToPOIResponse" : {
      "MessageHeader" : {
         "SaleID" : "POSSystemID12345",
         "ProtocolVersion" : "3.0",
         "POIID" : "MX925-123456789",
         "ServiceID" : "0207111140",
         "MessageClass" : "Service",
         "MessageCategory" : "TransactionStatus",
         "MessageType" : "Response"
      },
      "TransactionStatusResponse" : {
         "RepeatedMessageResponse" : {
            "RepeatedResponseMessageBody" : {
               "PaymentResponse" : {
                  "PaymentResult" : {
                     "PaymentInstrumentData" : {
                        "PaymentInstrumentType" : "Card",
                        "CardData" : {
                           "EntryMode" : []
                        }
                     },
                     "PaymentAcquirerData" : {
                        "MerchantID" : "TestMerchantPOS",
                        "AcquirerPOIID" : "MX925-260193322"
                     }
                  },
                  "POIData" : {
                     "POITransactionID" : {
                        "TimeStamp" : "2017-07-04T07:40:27.000Z",
                        "TransactionID" : "oLkO001499154027011"
                     }
                  },
                  "Response" : {
                     "AdditionalResponse" : "104 Merchant cancelled tx",
                     "Result" : "Failure",
                     "ErrorCondition" : "Cancel"
                  },
                  "SaleData" : {
                     "SaleTransactionID" : {
                        "TimeStamp" : "2017-07-04T07:40:46.000Z",
                        "TransactionID" : "12576"
                     }
                  }
               }
            },
            "MessageHeader" : {
               "POIID" : "MX925-123456789",
               "ServiceID" : "2345",
               "MessageType" : "Response",
               "MessageClass" : "Service",
               "MessageCategory" : "Payment",
               "SaleID" : "POSSystemID12345",
               "ProtocolVersion" : "3.0"
            }
         },
         "Response" : {
            "Result" : "Success"
         }
      }
   }
}
{
   "SaleToPOIResponse" : {
      "MessageHeader" : {
         "ServiceID" : "29235",
         "MessageCategory" : "TransactionStatus",
         "ProtocolVersion" : "3.0",
         "MessageType" : "Response",
         "SaleID" : "POSSystemID12345",
         "POIID" : "MX925-260193322",
         "MessageClass" : "Service"
      },
      "TransactionStatusResponse" : {
         "Response" : {
            "Result" : "Success"
         },
         "RepeatedMessageResponse" : {
            "MessageHeader" : {
               "MessageCategory" : "Payment",
               "ServiceID" : "2345",
               "ProtocolVersion" : "3.0",
               "MessageType" : "Response",
               "POIID" : "MX925-260193322",
               "MessageClass" : "Service",
               "SaleID" : "POSSystemID12345"
            },
            "RepeatedResponseMessageBody" : {
               "PaymentResponse" : {
                  "PaymentResult" : {
                     "PaymentInstrumentData" : {
                        "CardData" : {
                           "EntryMode" : []
                        },
                        "PaymentInstrumentType" : "Card"
                     },
                     "PaymentAcquirerData" : {
                        "AcquirerPOIID" : "MX925-260193322",
                        "MerchantID" : "TestMerchantPOS"
                     }
                  },
                  "POIData" : {
                     "POITransactionID" : {
                        "TimeStamp" : "2017-08-22T11:00:23.000Z",
                        "TransactionID" : "oLkO001503399623002"
                     }
                  },
                  "Response" : {
                     "AdditionalResponse" : "104 Merchant cancelled tx",
                     "ErrorCondition" : "Aborted",
                     "Result" : "Failure"
                  },
                  "SaleData" : {
                     "SaleTransactionID" : {
                        "TransactionID" : "17481",
                        "TimeStamp" : "2017-08-22T11:00:34.000Z"
                     },
                     "TokenRequestedType" : "Customer"
                  }
               }
            }
         }
      }
   }
}

The POITransactionID returned by the Terminal API consists of a PSP reference and a Tender reference. The format of the TransactionID is: < tenderref>.<pspref>, for example, oLkO001503399575001.9815033996072250.

If a PSP reference has not yet been generated, the TransactionID will only consist of a tender reference. This could occur if the transaction was completed offline.

The message above contains two MessageHeaders: one for the original message being reported on, and the message header of the response itself.

Data sent in response to TransactionStatusRequest

  • For the twenty most recent transactions per SaleID, we store the complete reply.

    For versions older than V1.22, the complete transaction information is stored for 10 minutes only.

  • When a TransactionStatusRequest is received, the system checks if the nexo process still has the details. If so, the complete original response is returned.
  • Receipt data is only included if requested by in the TransactionStatusRequest
  • Signature data is only included if a CashierReceipt is requested in the {TransactionStatusRequest}

There are 3 possible outcomes:

  • Success: the TransactionStatusResponse contains the result of the original payment request.
  • Failure: the transaction is still progress.
  • Failure: the transaction was not found (it was never started on the device).