Step 4. You Confirm the Transaction

On this page:

Overview

You will receive our notification POST over HTTPS when you have a valid SSL certificate installed on your website, or by HTTP when you do not.

Important:  HTTP POSTs are a security concern as the data packets can be intercepted by malicious players. For example, a NOTAUTHED Status could be fraudulently updated to OK. To mitigate the risk, the notification POST is appended with a VPSSignature. This effectively signs the POST with an MD5 hash of the contents of the message.

On receiving the POST, your site confirms the transaction status against your own records and replies to Opayo sending us the URL you want your customer to return to on your site.

    a. You Processes Our Notification POST

    Important: You must process and respond to the notification POST in all circumstances and irrespective of the Status. Without this acknowledgement the Opayo Transaction Monitor will cancel the transaction and notify you of the cancellation.

    Your notification script should read the VendorTxCode and VPSTxId from the POST and retrieve the relevant information about the order from your database including, most importantly, the transaction SecurityKey.

    The script will reconstruct the notification POST and parse it through an MD5 Hash algorithm.

    Note: Hash algorithms are one-way functions if you pass the same data through the same algorithm you’ll get the same signature value every time you run it. There is no way to regenerate the original data from the signature data, even if you know the algorithm used and the key. Hashing is a standard means of digitally signing messages in this manner.

    The script must then compare the value it has generated to the VPSSignature value in the POST:

    • When they match, then the message has not been tampered with.
    • If they do not match, then the POST may have been altered and you can decline the transaction.

    When you have confirmed that the POST has not been intercepted, you must store the notification POST TxAuthNo value in your database alongside the VendorTxCode, VPSTxId, and SecurityKey.

    Important: The TxAuthNo field DOES NOT contain the actual Authorisation Code sent by the bank. That is returned in the BankAuthCode field.

    The TxAuthNo contains a unique reference number to the Authorisation called the VPSAuthCode. This is a unique transaction ID sent to the bank during settlement so the bank can refer to the value if they contact you about the transaction.

    b. You Respond to the Notification Post

    You must process and respond to the notification POST in all circumstances and irrespective of the Status. Without this acknowledgement the Opayo Transaction Monitor will cancel the transaction and notify you of the cancellation.

    • If we do not receive a response from your notification script on our first attempt, we attempt to notify you a further 9 times at approximately 1 second intervals. This accounts for when your server is busy.
    • If you do not respond within 10 seconds (on the 10th attempt):
      • Card payment transactions are timed out by the Transaction Monitor. They cannot be settled, so your customer is not charged.
      • When the transaction times out, we will continue to send notification POSTs to your NotificationURL with a Status of ABORT. The transaction is cancelled.
    Note: As European Payment transactions are settled instantly, if there is a problem with our notifying you of the transaction, then it will complete with the status indicated by PPro. This means that it is possible that the transaction may have a different Status on your systems than that shown in MyOpayo. The correct status is that shown in MyOpayo.

    Response Content

    Your notification script should reply to our notification POST with three fields: 

    • Status. This indicates if you want to accept the transaction notification.
    • StatusDetail. This is the reason for accepting the transaction or not.
    • RedirectURL. This is the URL of your site's completion page that we will direct your customer to.

    You can reply with one Status from the list in the following table.

    Available Response Statuses

    Status

    Description

    OK

    Sent when you want to proceed to charge the customer.

    INVALID

    This indicates something is amiss with the POST. For example, because

    • The MD5 hash signatures did not match
    • You do not want to proceed with the order.

    ERROR

    This is rarely necessary and should ONLY be sent when something unforeseen has happened on your server or database. For example, when you receive a notification POST for a transaction, and you cannot identify its record.

    c. We Direct Your Customer to Your RedirectURL

    When we receive your response to our notification POST, we determine where to direct your customers browser based on your response Status:

    • When the Status is OK, this is normally acknowledging the transaction's completion. For example, we direct your customer to a page saying, “Thank you for your order. Reference 123456, please visit us again.”
    • If the Status is INVALID or ERROR, the RedirectURL will normally point to an error page with a support telephone number.

    When your response Status is not OK

    • The transaction will not be settled with the bank
    • Your customer is NOT charged for the goods or services.
    • You should not send the goods or services to your customer.

    Transactions successfully completed with PPro

    • Are marked as Successful in MyOpayo and
    • The money is debited from the customer’s account even when you return an INVALID or ERROR Status.

     

    ❮ Back to Step 3. Next: Step 5 ❯