Search docs

Are you looking for test card numbers?

Would you like to contact support?

Start searching Adyen's documentation...

  Documentation

Verify transaction status

Learn how to verify the status of a transaction when you don't receive a response.

While making a transaction, a communication or technical issue can prevent your cash register from receiving a synchronous response. Without this response your store staff may be unable to verify whether the transaction has been processed, or its result.

Instead of attempting to cancel or refund the transaction, or risking a duplicate transaction, you should request the transaction's status. This lets you verify whether the transaction is:

If the transaction has been processed you also receive the original transaction response, indicating its result.

If you are making frequent transaction status request then you may have a network connectivity issue. Make sure that your terminal is connected to the internet, and ensure that your integration meets our functional requirements.

Request transaction status

We recommend that your integration automatically requests the status of a transaction, any time it fails to receive the synchronous transaction response.

A transaction that isn't processed within 120 seconds will time out (resulting in a Cancelled transaction). So if you have not received the synchronous transaction response in this time, you should assume a communication or technical issue has occurred, and request the status of the transaction.

To request the status of a transaction, your cash register should:

  • Make a POST request to a Terminal API endpoint, specifying:

    • content-type: application/json
    • x-api-key: Your API key. This is only required if you're using cloud-based communications.
    • MessageHeader:

      • ProtocolVersion: 3.0
      • MessageCategory: TransactionStatus
      • MessageType: Request
      • SaleID: Your unique ID for the cash register making the transaction status request.
      • ServiceID: Your unique ID generated by this cash register for the transaction status request. This needs to be unique within the last 48 hours.
      • POIID: Unique ID of the terminal.

        The POIID = [Terminal model]-[Serial number], for example: P400Plus-123456789

    • TransactionStatusRequest:

      • ReceiptReprintFlag: true
      • DocumentQualifier: Receipt data you wish 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.

        • SaleID: The SaleID of the cash register that made the original transaction.
        • ServiceID: The ServiceID 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.

    The integration in this example uses synchronous, cloud-based communication.

    curl -H "content-type:application/json" -H "x-api-key:YOUR_API_KEY" -X POST --data-binary '{
      "SaleToPOIRequest": {
        "MessageHeader": {
          "ProtocolVersion": "3.0",
          "MessageClass": "Service",
          "MessageCategory": "TransactionStatus",
          "MessageType": "Request",
          "SaleID": "POSSystemID12345",
          "ServiceID": "29235status",
          "POIID": "V400m-324688179"
        },
        "TransactionStatusRequest": {
          "ReceiptReprintFlag": true,
          "DocumentQualifier": [
            "CashierReceipt",
            "CustomerReceipt"
          ],
          "MessageReference": {
            "SaleID": "POSSystemID12345",
            "ServiceID": "29235",
            "MessageCategory": "Payment"
          }
        }
      }
    }' --url https://terminal-api-test.adyen.com/sync

    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 the ErrorCondition:

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 the status of the transaction.

The example response below indicates that this transaction, a payment, was processed. The RepeatedResponseMessageBody object in the response indicates that the status of this transaction is 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":"Uncompleted transaction"
      }
    }
  }
}

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. This means that either:

  • The SaleID or ServiceID you specified in the transaction status request are incorrect. Check that you provided the SaleID and ServiceID of the original transaction in the TransactionStatusRequest.MessageReference.
  • We did not receive your transaction request.

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 not Found, last PaymentRequest has ID 29234"
      }
    }
  }
}

For a complete list of fields you can receive in a transaction status response, see the TransactionStatusResponse API reference.

Terminal API endpoints

For test transactions, use the endpoint below that corresponds to your integration architecture.

For more information on these architectures, see our Terminal API overview.

Local

Endpoints for local communications with the Terminal API use the format:

  • https://[TERMINAL]:8443/nexo/ on port 8443 (https).
    Replace [TERMINAL] with the IP or resolvable hostname of the terminal.

Cloud

For cloud-based communications with the Terminal API use either:

Next steps