While making a transaction, a communication or technical issue can prevent your cash register from receiving a response. Without this response your store staff may be unable to verify whether the transaction has been processed, or its result. They may also attempt to cancel or refund the transaction, or risk a duplicate transaction.
Instead, your integration should request the transaction's status to verify whether the transaction is:
If the transaction has been processed you also receive the original transaction response, indicating the result.
If you are making frequent transaction status requests then you may have a network connectivity issue. Make sure that your terminal is connected to the internet, and refer to our network recommendations.
Before you begin
Before you verify the status of a transaction with our Terminal API, make sure you have:
- Read and understood the Terminal API fundamentals.
- Made a transaction, such as a payment.
Request transaction status
We recommend that your integration automatically requests the status of a transaction, any time it fails to receive a transaction response.
Payment requests time out after 120 seconds. If you do not receive a payment response (or you receive a response indicating a time-out) after 120 seconds, and the network connection hasn't dropped, your integration should automatically request the transaction status.
To request the status of a transaction, your cash register should:
-
Make a POST request to a Terminal API endpoint, specifying:
If you're using cloud communications, make the request to a
/sync
endpoint.-
MessageHeader
: The standardSaleToPOIRequest.MessageHeader
object. This includes:Parameter Required Description ProtocolVersion
3.0 MessageClass
Service MessageCategory
TransactionStatus MessageType
Request SaleID
Your unique ID for the cash register. ServiceID
Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours. POIID
Unique ID of the terminal that you want to route this request to. Format: [device model]-[serial number].
-
TransactionStatusRequest
: The request body with:ReceiptReprintFlag
: true-
DocumentQualifier
: Receipt data you want to receive in the response. Can be one or both of:- CashierReceipt: Cashier receipt, including signature data.
-
CustomerReceipt: Shopper receipt.
-
MessageReference
: This object is optional. If you do not include it you receive the status of the most recent transaction made by the terminal that you route the transaction status request to.SaleID
: TheSaleID
of the cash register that made the original transaction.ServiceID
: TheServiceID
of the original transaction.-
MessageCategory
: The original transaction type, either:- Payment: Payment request.
- Reversal: Refund request.
- StoredValue: Request to activate or load balance on a gift card.
The example below shows how you would request the status of a payment with the
ServiceID
29235.{ "SaleToPOIRequest": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "TransactionStatus", "MessageType": "Request", "SaleID": "POSSystemID12345", "ServiceID": "29245", "POIID": "V400m-324688179" }, "TransactionStatusRequest": { "ReceiptReprintFlag": true, "DocumentQualifier": [ "CashierReceipt", "CustomerReceipt" ], "MessageReference": { "SaleID": "POSSystemID12345", "ServiceID": "29235", "MessageCategory": "Payment" } } } }
For a complete list of fields you can pass when requesting a transaction status, see the TransactionStatusRequest API reference.
-
The response contains a TransactionStatusResponse.Response.Result
, indicating whether the transaction has been processed:
-
Success
: Transaction has been processed. The original transaction response is also provided. -
Failure
: Transaction has not been processed. The reason is indicated by theErrorCondition
:-
InProgress
: Transaction is still being processed. -
NotFound
: We were not able to find the transaction.
-
An example of each result is provided below.
Transaction processed
A TransactionStatusResponse.Response.Result
of Success indicates that the transaction was processed. Use the original transaction response, provided in the RepeatedResponseMessageBody
object, to determine how to process the transaction.
The example response below indicates that this transaction, a payment, was processed. The RepeatedResponseMessageBody
object in the response indicates that the payment was successful (PaymentResponse.Response.Result
is Success).
{
"SaleToPOIResponse":{
"TransactionStatusResponse":{
"MessageReference":{
"SaleID":"POSSystemID12345",
"MessageCategory":"Payment",
"ServiceID":"29235"
},
"Response":{
"Result":"Success"
},
"RepeatedMessageResponse":{
"RepeatedResponseMessageBody":{
"PaymentResponse":{
"POIData":{
"POITransactionID":{
"TimeStamp":"2019-03-07T10:11:04+00:00",
"TransactionID":"4rVu001559643049000.981517998282382K"
},
"POIReconciliationID":"1000"
},
"SaleData":{
"SaleTransactionID":{
"TimeStamp":"2019-03-07T10:11:04+00:00",
"TransactionID":"29235"
}
},
"PaymentReceipt":[...],
"PaymentResult":{...},
"Response":{
"Result":"Success",
"AdditionalResponse":"...pspReference=981517998282382K..."
}
}
},
"MessageHeader":{
"SaleID":"POSSystemID12345",
"MessageClass":"Service",
"MessageCategory":"Payment",
"ServiceID":"29235",
"POIID":"V400m-324688179",
"MessageType":"Response"
}
}
},
"MessageHeader":{
"SaleID":"POSSystemID12345",
"MessageClass":"Service",
"MessageCategory":"TransactionStatus",
"ServiceID":"29235status",
"POIID":"V400m-324688179",
"MessageType":"Response"
}
}
}
For a complete list of fields you can receive in a transaction status response, see the TransactionStatusResponse API reference.
Transaction in-progress
A TransactionStatusResponse.Response.ErrorCondition
of InProgress indicates the transaction is still being processed. This is usually due to the terminal waiting for input from the shopper (for example, a tip or currency conversion request), but can also result from a delay with the card issuer.
We recommend that you continue to request the status of this transaction again each 5 seconds, until you receive a response indicating the transaction is processed.
The example response below indicates that this transaction is still in-progress.
{
"SaleToPOIResponse":{
"MessageHeader":{
"MessageType":"Response",
"MessageCategory":"TransactionStatus",
"MessageClass":"Service",
"ProtocolVersion":"3.0",
"POIID":"V400m-324688179",
"SaleID":"POSSystemID12345",
"ServiceID":"29235status"
},
"TransactionStatusResponse":{
"Response":{
"Result":"Failure",
"ErrorCondition":"InProgress",
"AdditionalResponse":"message=Uncompleted%20transaction"
}
}
}
}
For a complete list of fields you can receive in a transaction status response, see the TransactionStatusResponse API reference.
Transaction not found
A TransactionStatusResponse.Response.ErrorCondition
of NotFound indicates that we were not able to find the transaction with the SaleID
and ServiceID
you specified. The AdditionalResponse
has Message not found and echoes the category of the transaction (such as Payment), the SaleID
, and the ServiceID
you specified in the request.
When the transaction is not found, this means that either:
- The
POIID
,SaleID
orServiceID
you specified in the transaction status request are incorrect. Check that you provided thePOIID
,SaleID
, andServiceID
from the original transaction in theTransactionStatusRequest.MessageReference
. - We did not receive your transaction request. This could be due to a dropped internet connection or an unexpected power loss. You can attempt the original transaction again.
The example response below indicates that this transaction was not found.
{
"SaleToPOIResponse":{
"MessageHeader":{
"POIID":"V400m-324688179",
"SaleID":"POSSystemID12345",
"ServiceID":"29235-status",
"ProtocolVersion":"3.0",
"MessageCategory":"TransactionStatus",
"MessageType":"Response",
"MessageClass":"Service"
},
"TransactionStatusResponse":{
"Response":{
"ErrorCondition":"NotFound",
"Result":"Failure",
"AdditionalResponse":"message=Message%20not%20found.%20Category%3dPayment%2c%20last%20such%20Request%20has%20SaleID%3dPOSSystemID12345%20ServiceID%3d29235",
}
}
}
}