Implementing a Generic IPN Listener

You write your IPN listener in the scripting or programming language of your choice and host it on your web server. You can use the sample code provided by OKPAY as a starting point.

As a good programming practice, as well as to keep things simple, your IPN listener should listen for a post from OKPAY and dispatch it immediately to another routine or process that handles the business logic associated with the message. If your listener is structured in this way, it will be a simple and tight loop that listens for a message and dispatches it for processing by your application logic.

Your listener software must:

  1. Wait for an HTTP post from OKPAY.
  2. Create a request that contains exactly the same IPN variables and values preceded by "ok_verify=true".
  3. Post the request to "https://checkout.okpay.com/ipn-verify".
  4. Wait for a response from OKPAY, which is either VERIFIED or INVALID (for IPN simulation testing response may be TEST or INVALID).
  5. If the response is VERIFIED, perform the following checks:
    • Depending on the message type, various ok_txn_kind should be checked. For payments, e.g. ok_txn_kind is payment_link, etc.
    • Confirm that the payment status is Completed (ok_txn_status=completed).
      OKPAY sends IPN messages for pending and denied payments as well; do not ship until the payment has cleared.
    • Use the transaction ID (ok_txn_id) to verify that the transaction has not already been processed; this prevents duplicate processing of transactions.
      Typically, you store transaction IDs in a database so that you know you are only processing unique transactions.
    • Validate that the receiver's email address (ok_receiver_email) is registered to you.
      This check provides additional protection against fraud.
    • Verify that the price, item description, and so on, match the transaction on your website.
      This check provides additional protection against fraud.
  6. If the verified response passes the checks, take action based on the value of the ok_txn_status variable; otherwise, take action based on the value of the ok_txn_pending_reason variable.
  7. If the response is INVALID, save the message for further investigation.

Hint: For additional security we suggest hiding your IPN handler file from third parties, e.g. place the script in a secret folder and/or use non-obvious file names, do not allow search engine robots to scan that folder to prevent abuse of your script and corresponding business logic, etc.

Sample Code

Since IPN handlers can be used for several different purposes, the handler's implementation will also vary, so you should look at examples of each individual application in the corresponding Integration Guide in the relevant section (code samples).

OKPAY RSS
OKPAY Forum
OKPAY on Facebook
OKPAY on Livejournal
OKPAY on Twitter
OKPAY on VK
OKPAY on Linkedin
OKPAY on Youtube