IPN Guide
Overview
Plimus Instant Notifications (also referred to as IPNs) integrate information from the Plimus Platform with a Seller or Affiliate's backend operations.
Basic transaction details, such as price, product, and buyer's information, are automatically transmitted to a unique URL set up and defined by you on your site server and can be connected to your backend system.
The information transmitted and collected is similar to that contained in a confirmation email relating to the transaction. The main advantage is that the content is sent immediately and optionally stored in your system or database.
This is helpful as you get real time reporting of relevant events, such as sale and refund requests. By collecting such data in a databank, you will be better able to observe results over time and plan your ongoing sales strategy more effectively.
Instant Notifications are delivered via an HTTP POST and are triggered by an appropriate event, such as authorization, payment acceptance, or refund confirmation.
Terms of Use & Implementation Advice
The Plimus Instant Notification service is provided free of charge by Plimus. A sample PHP code script is provided as well, and you are invited to test and install this on your server. Plimus reserves the right to expand, modify or restrict the service in the future.
We recommend that IPNs are only set up and used by persons familiar with such services. IPNs require a minimum level of expertise to work successfully. If you are not familiar with these services, Plimus suggests you contact an consultant in this field for assistance.
The Plimus Instant Notifications service is offered on an ‘as is' basis, and Plimus provides the service and related scripts without warranty or liability as to its functioning on your particular system. Effective use of IPNs can increase the value of information flowing into your backend system and improve commercial decision-making processes.
To protect the script from unauthorized use, connection availability is limited to the following public Plimus IP addresses:
62.216.234.(196-222)
72.20.107.(242-250)
209.128.93.(97-110)
209.128.93.(225-255)
What are Plimus Instant Notifications?
Plimus Instant Notifications are simple HTTP(S) POST communications, which transmit all data elements of a payment transaction to the Plimus user, except personal payment method data (i.e. credit card number).
In order to assign the data from a Plimus Instant Notification to another program, such as CRM or ERP, the Plimus Vendor or Affiliate needs to prepare a web-available script to which the IPN is directed. This script takes all the details contained on the IPN and distributes them across any and all affected systems for update.
The IPN communication comprises a batch of URL parameters related to the online transaction. Each notification contains a post request and contains pre-defined parameters. The data will either be in a ‘Yes' or ‘No' format, a number, an information string or date and time details. Typical data would be a Plimus reference number, payment method, contract id, contract price, referrer URL, shipping address details, invoice amount, and so on.
What Can I Do With Plimus Instant Notifications?
Using Plimus Instant Notifications enables you to collect and store relevant business data in real time. This makes it easier to track what is happening across your enterprise. You will be able store accurate records, keep details of licenses, fulfill orders, provide technical support, maintain customer lists for use with newsletters, issue credit card update reminders, review affiliate performance and perform reconciliations with Plimus payments, and accounts reports.
In addition to providing data on transactions, Plimus offers IPN capability to receive details of customer logins to their accounts through Plimus. This is especially helpful when customers are dealing with a subscription or recurring charge-based product. A customer login account can be created which then can track account changes made by customers using the Plimus Instant Notification process.
How Do Plimus Instant Notifications Work?
After setting the appropriate URL to receive information postings, the Plimus platform initiates an information output to your stated URL, each time a triggering event within a transaction occurs. Plimus only issues data posts that conform to the items as set out in our published lists of Instant Payment Notification Variables for both Sellers and Affiliates as linked below. The variables are revised and new functionality is added to from time to time so we recommend that you review the published list on a regular basis.
Your IPN URL must be correctly set up to process these posts.
Transaction Types
The following transaction events are recognized by the Plimus system and act to trigger an instant notification post:
Charge: This is the IPN event most commonly monitored by Plimus Sellers. The system issues a notification when a new purchase has been completed. The monies have been received by Plimus, and are held on account for the respective Seller. A Charge notification will be issued, specifying payment details of the first installment in a recurring contract or subscription contract.
Refund: Notification is given as soon as a refund is issued. Following a refund request by a customer, the Seller may issue a refund, or this may be activated by Plimus. Immediately after the refund is granted, monies are moved to the customer's account and a notification is sent.
Chargeback: The Chargeback procedure is usually instigated by a customer. A notification is sent when the Chargeback is filed at Plimus, and the monies are re-credited back to the Customer.
Authorization Only: A recurring contract or subscription transaction can be set to check the validity of a purchaser's account details. This step is known as an 'Authorization Only' process. In this instance, when the initial transaction occurs, the Vendor can opt for the BuyNow page to trigger an account check to verify the purchaser's account details. In such circumstances an 'Authorization Only' notification will be sent indicating the account is authorized. No charges occur at this stage.
Recurring: This notification is given once a charge has been made on a recurring or subscription contract. This applies only to the second and subsequent charges, as the first payment on such contracts is treated as a standard Charge, and results in a 'Charge' notification.
This notification is also sent on a subscription renewal.
Cancellation: A cancellation notification is issued when a recurring charge is cancelled - such cancellation may be activated by the customer, the Seller or Plimus.
Cancellation Refund: A Cancellation Refund notification is sent when a contract is cancelled as above and a refund is processed.
Contract Change: This notification is issued when the contract associated with a recurring charge or a subscription contract is replaced with another contract, such as a customer moving from one service plan to another.
Cancellation Chargeback: If a chargeback is raised on a recurring/subscription contract then the subscription is also cancelled and this notification is generated.
Cancel: This notification is issued when a transaction is cancelled following manual review, the most likely reason being suspected fraud.
Decline: Plimus issues this notification when an order is declined on manual review. This can be for a variety of reasons and the customer will also be notified of this decision by email.
List of Variables
A list of notification variables setting out the available parameters is published for both Sellers and Affiliates. These list the specific parameters that can be used, and the transaction types for which notifications are generated.
Variables for Sellers:
Variables for Affiliates:
Transaction Flow Example
The graphic below depicts an example transaction in which a customer has purchased a software program with a CD on Demand, using a Credit Card for payment.
Subsequently the customer discovers that the program is unsuitable and issues a refund request, which is accepted by the Seller. As a result the transaction is cancelled and monies are refunded. The IPN incidences are marked below.
Set Up on the Plimus Platform
For the most part, setting up IPN functionality on Plimus is straightforward. The main challenge is usually that of setting up a script that will work with your back end system.
The default URL for the Notification process can be set up at your account level through the general settings interface.
Account Level Set Up
Sellers and Affiliates may set up notifications by adding the relevant URL address to the IPN box on the General Settings page. This acts as the overall default for the Seller’s account. This URL can be overridden at Contract level if a different URL is specified in a Contract Settings page.
Here is an example of the default set up at account level through the General Settings interface:
Advanced users can request a notification receipt which sets up a data ‘handshake’ operation that ensures notifications are coming from Plimus. This requires the accurate set up of a data encryption key in the Plimus system in order to avoid automatic failure messages.
Contract Level Set Up
Sellers must also activate notifications for each contract from the relevant contract settings page.
Here we see notifications being activated at contract level by checking the relevant box, and also the default URL being overridden:
Plimus will post the relevant HTML Notification Variables to the stated IPN URL. The URL used must include relevant scripts to handle the various data parameters posted by Plimus. To help reduce difficulties setting up the script, Plimus provides a PHP sample.
Using Notifications to Capture Login Credentials
Sellers offering subscriptions often provide their customers with the ability to log into an account page and perform various functions relating to their subscription such as renewing subscription period, changing credit card details, updating account password particulars etc.
Such changes can be automatically followed and fed into the Seller’s backend system using the Capture Login Credentials interface provided at the Contract Settings level.
An additional use of this functionality is the ability to use parameters relating to the credit card expiry date and last four digits in order to issue automated reminders to customers to update their credit card details prior to expiry.
Encrypted Notifications
Advanced users can set up encrypted notifications to improve security and prevent unauthorized changes to sensitive parameters. This functionality is available at contract level using additional Parameters Protection interface shown:
Testing
We recommend that you test your IPN set up using the Plimus Sandbox. If you do not already have a logon for the Sandbox, set up a free Vendor or Affiliate account at sandbox.plimus.com.
To test a typical credit card transaction you can use a fictitious name and number as supplied to you on request by the Seller support team.
Support Issues
You can request support from the Plimus Seller Support team through the normal control panel link located on the top right hand corner of the control panel.
In the event that the Plimus system is unable to reach the URL you have specified, an automated email will be issued to your account advising of this problem.
Coding Example
A PHP coding example is available for your assistance. Please note, that Plimus Seller Support is unable to provide support relating custom coding requests.
