Instant Payment Notification (IPN) Overview
Instant Payment Notification (IPN) is a message service that notifies you of events related to OKPAY transactions. You can use IPN messages to automate back-office and administrative functions, such as fulfilling orders, tracking customers, and providing status and other transaction-related information.
The IPN service notifies you when an event occurs that pertains to a transaction. Typically, these events represent various kinds of payments; however, the events may also represent change in subscription status, client verification authorisation, and other actions, such as refunds, disputes, and chargebacks.
IPN is a message service that OKPAY uses to notify you about events, such as:
- Instant payments;
- Pending payments (including payments being reviewed for potential fraud);
- Authorisations (indicating a sale whose payment has not yet been collected);
- Recurring payments and subscription payment actions;
- Chargebacks, disputes, reversals, and refunds associated with different transactions.
In many cases, the action that triggers an IPN event is a user-action on your website. However, other actions can trigger trigger IPNs. For example, your site's back-office process might invoke an OKPAY API that refunds a payment, or a customer might notify OKPAY of a disputed charge.
You receive and process IPN messages with a listener (sometimes called a handler), which is a program that you write. This program waits for IPNs and (typically) passes them to an administrative process that responds appropriately. OKPAY provides sample code that you can modify to implement a listener that handles IPN messages.
These actions to take when your listener is notified of an event are application-specific. Here are some common actions that applications take in response to IPN messages:
- Trigger order fulfillment or enable media downloads;
- Update a list of customers;
- Update accounting records;
- Create specialised "to do" lists.
In addition to IPN messages, you are notified of events by e-mail. However, unlike e-mail, IPN messages let you automate responses to events. The diagram below shows various events that can occur and how OKPAY responds by sending IPN messages to your listener.
Figure 1. IPN Overview.
The diagram shows requests and responses that are the result of processing button clicks or API functions at OKPAY. OKPAY sends an IPN message when it sends a response to a request. However, the IPN message is not actually part of the response sent to your website. Rather, the IPN message is sent to the your listener. This feature lets you take actions that are not directly tied to the operation of your website.
Note: The diagram does not show the IPN authentication protocol that a listener must implement to validate an IPN message. This protocol is discussed in detail below.
IPN is an asynchronous message service, meaning that IPNs are not synchronised with actions on your website. Thus, listening for an IPN message does not increase the time required to complete a transaction on your website.
The IPN message service does not assume that your listener will receive all IPN messages. Because the Internet is not 100% reliable, IPNs can get lost or be delayed. To address these issues, the IPN message service includes a retry mechanism that re-sends a message at various intervals until your listener acknowledges receipt:
- first 5 tries, an attempt every 30 minutes;
- then the next 5 tries, an attempt every 2 hours;
- then the next 5 tries, an attempt every 12 hours.
An IPN message may be re-sent up to four days after the original was sent. The maximum number of retries is 15.
Note: Although the Internet may be at fault, the most likely cause of lost, delayed or duplicate IPN messages is faulty logic in the listener itself.
Because IPN messages can arrive at any time, your listener should always be available; however, the IPN retry mechanism handles the cases when your listener is down temporarily.
The IPN message service is not a real-time service. As a result, your listener may not receive an IPN message for many seconds after an event occurs. Consequently, your checkout flow should not depend upon receiving an IPN message to complete. If it does, your checkout flow will be slow during periods of heavy system load; and complicated, since it must handle retries.
IPN Protocol and Architecture
The IPN message service is designed to be secure, reliable and asynchronous. To meet these requirements, the protocol requires that you acknowledge receipt of IPN messages. The IPN service provides a retry mechanism to handle cases in which a message is not acknowledged, e.g., when a transmit or receive failure occurs.
If you enable the IPN service, OKPAY sends messages to the IPN listener at the URL you specify in your account profile. If you want, you can override this URL in order to associate a different IPN listener with a specific transaction. To do this, you can either:
- Specify the URL of a different listener in your definition of an OKPAY button
- Pass the URL of a different listener to a call of an OKPAY API function
The IPN message authentication protocol consists of four steps:
- OKPAY HTTP POSTs your listener an IPN message that notifies you of an event.
- Your listener returns an empty HTTP 200 response to OKPAY.
- Your listener HTTP POSTs the complete, unaltered message back to OKPAY; the message must contain the same fields (in the same order) as the original message and be encoded in the same way as the original message.
- OKPAY sends a single word back - either VERIFIED (if the message matches the original) or INVALID (if the message does not match the original).
Your listener must respond to every IPN message it gets, whether you take action on it or not. If you do not respond, OKPAY assumes the IPN was not received and re-sends it. Further, OKPAY continues to re-send the message periodically until your listener responds, although the interval between retries increases with each attempt. An IPN will be resent for up to four days, with a maximum of 15 retries.
This re-send algorithm can lead to situations in which OKPAY re-sends an IPN message at the same time you are sending back the original message. In this case, you should send your response again, to address the possibility that OKPAY did not receive your first response. You must also ensure that you do not process the transaction associated with an IPN message twice.
- Every IPN message you receive from OKPAY includes a User-Agent HTTP request header whose value is OKPAY IPN (https://www.okpay.com/ipn-verify.html). Do not use this header to verify that an IPN really came from OKPAY and has not been tampered with. Rather, to verify these things, you must use the IPN authentication protocol outlined above.
- OKPAY expects to receive a response to an IPN message within 30 seconds. Consequently, your listener must not perform time-consuming operations (such as updating a database) before responding to an IPN.
After OKPAY verifies an IPN, your listener or administrative software should make these additional checks:
- Verify that you are the intended recipient of the IPN message.
To do this, check the e-mail address in the message. This check prevents another merchant from accidentally or intentionally using your listener.
- Verify that the IPN is not a duplicate.
To do this, save the transaction ID and last payment status in each IPN message in a database and verify that the current IPN values for these fields are not already in this database.
Moreover, OKPAY sends the variable
ipn_id which contains the unique ID of the received IPN message. You can use it to prevent re-processing of the same IPN in your business logic.
Note: You can't rely on transaction ID alone to screen out duplicates, as this scenario shows: 1) OKPAY sends you an IPN notifying you of a pending payment. 2) OKPAY later sends you a second IPN telling you that the payment has completed. However, both IPNs contain the same transaction ID; therefore, if you were using just transaction ID to identify IPNs, you would treat the "completed payment" IPN as a duplicate.
- Ensure that you receive an IPN whose payment status is "completed" before shipping merchandise or enabling download of digital goods.
Because IPN messages can be sent at various stages in a transaction's progress, you must wait for the IPN whose status is "completed' before handing over merchandise to a customer.
- Verify that the payment amount in an IPN matches the price you intend to charge.
If you do not encrypt your button code, it's possible for someone to capture a button-click message and change the price it contains. If you don't check the price in an IPN against the real price, you could accept a lower payment than you want.
IPN Message Generation and Flow
OKPAY sends your listener an IPN message when any of these things happens:
- A user on your website clicks an OKPAY payment button (e.g., a Buy Now button) and completes payment on OKPAY's site.
- Your back-office application invokes an OKPAY API function (for instance, Send_Money).
- OKPAY observes an external event, such as a dispute, chargeback, or various recurring payment and subscription events.
In the first case, your customer is redirected from your web app to OKPAY for some or all steps of the transaction. When the user completes payment, OKPAY sends an asynchronous IPN message to your listener.
In the second case, your customer is not redirected to OKPAY; instead, the user enters all payment information on your site. Again, when the user completes payment, OKPAY sends an asynchronous IPN message to your listener.
In the third case, IPN messaging is initiated by either your back-office process or by OKPAY itself (as opposed to an end-user). The IPN message is still sent asynchronously, but there is no web flow involved.
No matter what causes OKPAY to send an IPN message, your site can use such messages to kick off order fulfillment, enable digital media downloads, store information in a customer relationship management (CRM) or accounting system, and so on. However, before you do any of these things, you must be certain that the IPN has not been tampered with. To do this, your listener must implement the IPN authentication protocol. The left side of the diagram below shows this particular protocol.
Figure 2. IPN Message Generation and Flow.
The numbers in the diagram correspond to the following actions:
- A user clicks an OKPAY button to kick off a checkout flow; your web application makes an API call; your back-office system makes an API call; or OKPAY observes an event.
- OKPAY HTTP POSTs your listener an IPN message that notifies you of this event.
- Your listener returns an empty HTTP 200 response.
- Your listener HTTP POSTs the complete, unaltered message back to OKPAY.
Note: This message must contain the same fields, in the same order, as the original IPN from OKPAY, all preceded by
ok_verify=true. Further, this message must use the same encoding as the original.
- OKPAY sends a single word back - either VERIFIED if the message matches the original, or INVALID if the message does not match the original (for IPN simulation testing the response may be TEST or INVALID).
Remember: To prevent fraud, your IPN listener must implement the IPN authentication protocol (left side of the diagram above). Upon receipt of a VERIFIED response, your back-office process can parse the contents of the IPN message and respond appropriately - print a packing list, enable a digital download, etc.
Sample IPN Message and Response
An IPN message consists of variables that describe the transaction. These variables contain information about you, your customer, and the details of the transaction itself.
OKPAY sends a message, similar to the following one, for a €19.95 purchase made via OKPAY checkout:
ok_charset=utf-8&ok_receiver=OK702746927&ok_receiver_id=666146284&ok_receiver_wallet=OK702746927&ok_txn_id=1959454&ok_txn_kind=payment_link&ok_txn_payment_type=instant&ok_txt_payment_method=OKB&ok_txn_gross=19.95&ok_txn_amount=19.95&ok_txn_net=19.95&ok_txn_fee=0.00&ok_txn_currency=EUR&ok_txn_datetime=2013-06-01 04:18:32&ok_txn_status=completed&ok_invoice=9&ok_payer_status=unverified&ok_payer_id=654347086&ok_payer_reputation=0&ok_payer_first_name=John&ok_payer_last_name=Doeemail@example.com&ok_items_count=1&ok_item_1_name=OKPAY Poster&ok_item_1_type=digital&ok_item_1_quantity=1&ok_item_1_gross=19.95&ok_item_1_price=19.95
|Information about you:
|ok_receiver = OK702746927
|ok_receiver_id = 666146284
||Receiver account ID
|ok_receiver_wallet = OK702746927
||Check wallet ID to make sure that this is not a spoof
|Information about the transaction:
| ok_txn_id = 1959454
||Keep this ID to avoid processing the transaction twice
|ok_txn_payment_method = OKB
|ok_txn_payment_type = instant
||Type of transaction
|ok_txn_kind = payment_link
|ok_txn_status = completed
||Status, which determines whether the transaction is complete
|Information about your buyer:
|ok_payer_status = unverified
||Payer verification status in OKPAY
|ok_payer_id = 654347086
||Payer account ID
|ok_payer_first_name = John
||Payer first name
|ok_payer_last_name = Doe
||Payer last name
|ok_payer_email = firstname.lastname@example.org
|Information about the payment:
|ok_txn_gross = 19.95
|ok_txn_amount = 19.95
|ok_txn_net = 19.95
|ok_txn_fee = 0.00
|ok_txn_currency = EUR
|ok_txn_datetime = 2013-06-01 04:18:32
||Transaction date and time
|ok_item_1_name = OKPAY Poster
|ok_item_1_type = digital
|ok_item_1_quantity = 1
|ok_item_1_gross = 19.95
|ok_item_1_price = 19.95
|ok_invoice = 9
|Other information about the transaction:
|ok_ipn_id = 1234567
||IPN message ID
|ok_charset = utf-8
Before you can trust the contents of the message, you must first verify that the message came from OKPAY. To verify the message, you must send back the contents in the exact order they were received and precede it with the command
ok_verify=true, as follows:
https://checkout.okpay.com/ipn-verify?ok_verify=true&ok_charset=utf-8&ok_receiver=OK702746927&ok_receiver_id=666146284&ok_receiver_wallet=OK702746927&ok_txn_id=1959454&ok_txn_kind=payment_link&ok_txn_payment_type=instant&ok_txt_payment_method=OKB&ok_txn_gross=19.95&ok_txn_amount=19.95&ok_txn_net=19.95&ok_txn_fee=0.00&ok_txn_currency=EUR&ok_txn_datetime=2013-06-01 04:18:32&ok_txn_status=completed&ok_invoice=9&ok_payer_status=unverified&ok_payer_id=654347086&ok_payer_reputation=0&ok_payer_first_name=John&ok_payer_last_name=Doeemail@example.com&ok_items_count=1&ok_item_1_name=OKPAY Poster&ok_item_1_type=digital&ok_item_1_quantity=1&ok_item_1_gross=19.95&ok_item_1_price=19.95
OKPAY will then send one single-word message, VERIFIED, if the message is valid; otherwise, it will send another single-word message, INVALID.
Important: After you have authenticated an IPN message (that is, received a VERIFIED response from OKPAY), you must perform these important checks before you can assume that the IPN is both legitimate and has not already been processed:
- Check that the
ok_txn_status is "completed".
- If the
ok_txn_status is "completed", check the
ok_txn_id against the previous OKPAY transaction that you processed to ensure the IPN message is not a duplicate.
- Check that the
ok_receiver_email is an email address registered in your OKPAY account.
- Check that the price (carried in
ok_txn_gross) and the currency (carried in
ok_txn_currency) are correct for the invoice (carried in
Once you have completed these checks, IPN authentication is complete. Now you can update your database with the information provided and initiate any relevant back-end processing.
Use these resources to learn more about IPN features: