What is the IPN system and how can I use it?

What is the IPN system and how can I use it?

What is the IPN system and how can I use it?

The IPN system notifies your website whenever a customer initiates an order and whenever an order status is changed. This means that whenever a buyer completes a purchase or charges back, your webservice will receive a web notification.

IPN Notification Payload

After you enable IPN Notifications for your products and have successfully setup IPN Notifications on your website, you will receive a post request every time a buyer has purchased a product and paid for the product in its entirety.

To verify the integrity of the payload, we will send an HMAC signature over a HTTP header called “IPN_HASH”. The HMAC signature will be a signed json encoded POST object with your IPN secret. You can see how to verify the signature in the example_rocketr_ipn.php file in this repository.

We will send the following information in the post request as a JSON Object:

  • order_id
    • This is a unique string of 12 characters that identifies each order.
  • product_title
    • This the product title for which the IPN is being sent.
  • product_id
    • This the product id for which the IPN is being sent.
  • buyer_email
    • The email address of the buyer.
  • buyer_ip
    • The IP Address of the buyer (note this can be in IPv4 or IPv6 format)
  • payment_method
    • This is a number that represents the payment method used for the purchase:
      • 0 = Paypal
      • 1 = Bitcoin
      • 2 = Ethereum
      • 3 = Perfect Money
      • 4 = Stripe
  • invoice_amount_usd
    • This is a decimal value of the amount the buyer was invoiced (and the amount the buyer paid in USD)
  • quantity
    • The number of items the buyer purchased.
  • purchased_at
    • A MySQL DateTime object signifying the time the invoice was generated (formatted as Y-m-d H:i:s)
  • txn_id
    • This is a string that represents a transaction id for the payment method used to purchase the product. For example, this can refer to payapl’s transaction id, btc/eth’s blockchain ID, or perfect money id
  • status
    • This is an integer value that refers to the order status. Please see sample code for more information.
  • custom_fields
    • This contains all the custom fields that may have been associated with the order.
    • You can use custom fields to, for example, ask the buyer for their account username/id/email associated with an account on your website

How to Setup IPN Notifications on Your Website

Setting up IPN notifications is extremely easy. Take a look at the example_rocketr_ipn.php file in this repository and edit it to suit your needs.

How to Enable IPN Notifications for Your Products

  1. In order to receive instant payment notifications, you must first add an IPN secret by visiting the account settings page which can be found here. alt text
  2. Afterward, you must add a product and ensure you add the the url you wish to receive IPN notifications as show here alt text
  3. That’s it. It’s that simple. Now, whenever someone purchases your product, you will receive a post request (as shown above) containing order information.

Firewall Considerations

In order to ensure that you consistently received Instant Payment Notifications from rocketr, please make sure that you have whitelisted in your firewall.

in Integrations and APIs