Help and Support

IPN (Webhook) Setup

Suggest Edits

To set up IPNs (also known as webhooks), you will first set up the server and URL on your side, and then configure the IPN settings in your BlueSnap account. Once setup is complete, you may want to run a test to simulate an IPN.

IPN types and parameters

IPNs are sent as POST requests that contain parameters with data about the event.

For a list of available IPNs, see Default IPN types and On-demand IPN types.

For descriptions of all parameters that can be sent in an IPN, see IPN parameter reference.

1. Setting up your server to receive IPNs

In order to receive and process BlueSnap IPNs, you need to set up your server and provide a URL where the IPNs can be sent.

SSL is required. Please ensure that your server is configured to support HTTPS, with a valid server certificate.

IPN request-response flow

Request: Your server should listen for the IPN messages from BlueSnap. These are typically sent in real time with each event.

Response: Once you receive the IPN message, you should send an empty HTTP 200 response to BlueSnap.

If BlueSnap does not receive a confirmation that you received the IPN, we will resend the IPN every 4 hours, up to 11 attempts. Note: Only Default IPN types will be resent.

IP addresses used to send notifications

The IPNs will be sent only from these BlueSnap IP addresses, so you may want to whitelist these IPs:

BlueSnap Production

  • 62.216.234.216
  • 209.128.93.254
  • 209.128.93.98
  • 38.99.111.60
  • 38.99.111.160
  • 141.226.140.100
  • 141.226.141.100
  • 141.226.142.100
  • 141.226.143.100

BlueSnap Sandbox

  • 209.128.93.232
  • 62.216.234.196
  • 38.99.111.50
  • 38.99.111.150
  • 141.226.140.200
  • 141.226.141.200
  • 141.226.142.200
  • 141.226.143.200

Code samples

The following JSP examples show how a merchant can capture and log the IPN data sent from BlueSnap. These IPN receiver examples check whether the IPN comes from BlueSnap servers, decode and parse the IPN, and then print the IPN to a log. There is a separate IPN receiver example for Production and Sandbox, with the relevant IP addresses per environment.

Production Environment

<%@page import="java.util.Arrays"%>
<%@page import="java.util.HashSet"%>
<%@page import="java.util.Set"%>
<%@page import="java.net.URLEncoder"%>
<%@page import="java.util.Map"%>
<%@ page language="java" contentType="text/html; charset=utf-8" pageEncoding="utf-8"%>

<%
String ipAddress = request.getRemoteAddr();

Set blueSnapIps = new HashSet(Arrays.asList("62.216.234.216, 209.128.93.254, 209.128.93.98, 38.99.111.60, 38.99.111.160, ..."));
if (blueSnapIps.contains(ipAddress)) {
Map parameters = request.getParameterMap();
for (String parameter : parameters.keySet()) {
System.out.println("[" + parameter + "=" + java.net.URLDecoder.decode(parameters.get(parameter)[0], "UTF-8") + "]");
}
}
else {
System.out.println(ipAddress + " is not a BlueSnap server!!!");
}
%>

Sandbox Environment

<%@page import="java.util.Arrays"%>
<%@page import="java.util.HashSet"%>
<%@page import="java.util.Set"%>
<%@page import="java.net.URLEncoder"%>
<%@page import="java.util.Map"%>
<%@ page language="java" contentType="text/html; charset=utf-8" pageEncoding="utf-8"%>

<%
String ipAddress = request.getRemoteAddr();

Set<String> blueSnapIps = new HashSet<String>(Arrays.asList("209.128.93.232, 62.216.234.196. 38.99.111.50, 38.99.111.150, ..."));
if (blueSnapIps.contains(ipAddress)) {
Map<String, String[]> parameters = request.getParameterMap();
for (String parameter : parameters.keySet()) {
System.out.println("[" + parameter + "=" + java.net.URLDecoder.decode(parameters.get(parameter)[0], "UTF-8") + "]");
}
}
else {
System.out.println(ipAddress + " is not a BlueSnap server!!!");
}
%>

Back to Top

2. Enabling IPNs in BlueSnap

Using secure URLs

IPNs are transmitted via an HTTPS POST request to a unique URL on your site's server, which you will define. Each URL must use the HTTPS protocol or the URL will not be accepted.

We recommend that you enable IPNs for your entire BlueSnap account, which will apply your IPN settings to all contracts in your account.

You can then define a different IPN URL for a specific contract, if needed.

Configuring your account IPN settings

The following steps describe how to enable IPNs for your account and add the IPN URLs to your account settings. Once this is complete, BlueSnap will begin sending IPNs to your URLs in real-time.

  1. In the BlueSnap Merchant Console, go to Settings > General Settings.

  2. In the Notifications section, select the Receive Instant Payment Notifications check box.

  1. In the IPN URL(s) field, enter the SSL enabled URL where you want to receive the IPNs from BlueSnap. All Default IPN types will be sent to this URL. Once you have entered your URL, you can test it by clicking the "Test URL" button to the right of the entry field.

  2. To have additional On-demand IPN types sent to this URL, select the checkbox next to each IPN type that you want to receive.

  3. If you're hosting your product catalog on BlueSnap, you'll want to go to Product Catalog > Products in the left menu of the console. Expand the relevant product to view, click the contract's name, select "Receive Instant Payment Notifications (IPN)" in the Notifications section, and select "Use IPN URL as defined in General Settings." Failure to follow this step will result in the IPN's not being sent.
    Note: If you're not hosting your product catalog on BlueSnap, you can skip to step 6.

  1. To have the IPNs sent to an additional URL, click Add IPN URL, and then enter the additional URL where you want to receive the IPNs from BlueSnap.

  2. If you would like the Default IPN types to be sent to this additional URL, select the Send Default IPNs checkbox.

  1. To have additional On-demand IPN types sent to this URL, select the checkbox next to each IPN type that you want to receive. Note that any IPN types you select here will also be sent to your main IPN URL.

  2. Click Submit.

Back to Top

Configuring a separate IPN URL for a specific contract

Follow these steps to define a different IPN URL for a specific contract. This will override the global IPN URL defined for the account.

  1. In the BlueSnap Merchant Console, go to Product Catalog > Products in the left menu.

  2. Expand the relevant product to view its contracts, and then click the name of the contract where you want to set up an IPN.

  3. In the Notifications section, select the Receive Instant Payment Notifications check box.

  4. Select Use a specific IPN URL for this contract and enter the URL(s) where IPNs for this contract should be sent. All Default IPN types will be sent to this URL.

  5. To have additional On-demand IPN types sent to this URL, select the checkbox next to each IPN type that you want to receive.

  6. To have the IPNs sent to an additional URL, click Add IPN URL, and then enter the additional URL where you want to receive the IPNs from BlueSnap.

  7. If you would like the Default IPN types to be sent to this additional URL, select the Send Default IPNs checkbox.

  8. To have additional On-demand IPN types sent to this URL, select the checkbox next to each IPN type that you want to receive. Note that any IPN types you select here will also be sent to your main IPN URL.

  9. Click Submit.

Back to Top

3. Testing IPNs

Before you go live, it is recommended to test your IPNs and ensure you properly receive, process, and respond to the notifications.

Troubleshooting

If you have set up your IPN URL but you do not receive an IPN, you can follow these troubleshooting steps:

  1. Resend the IPN: In the Merchant Console, click Find a Transaction, then go to one of your existing order records. In the Resend Menu, select IPN, and click Send.

  1. Verify that the IPN URL is set up at both the account and contract level: Check the account-level IPN settings under Account Settings > General Settings > Notifications. In some cases, you may have different IPN settings for a contract, which will override your account-level IPN settings. Check the contract-level IPN settings on the General contract settings page, under Notifications.

  2. Try simulating an IPN, as described below.

  3. If you still don’t receive IPNs, contact Merchant Support.

Back to Top

Simulating an IPN

There are two ways to simulate an IPN which will help you verify that you are receiving the IPNs and debug any potential issues.

Option 1:

  1. In the BlueSnap Merchant Console, go to Settings > General Settings.

  2. Using the IPN Simulator, select the IPN you want to test and enter the URL to use for testing.

  3. Click Generate IPN.

  4. The IPN Simulator will generate the selected IPN and send it to the URL entered. The parameters in each IPN will be the same parameters used in production; however, the values returned will be generic.

Option 2:

  1. In the BlueSnap Merchant Console, go to Settings > General Settings.

  2. Enter your email address in the Admin email address field so that you will receive any emails about IPN errors, then click Submit.

  3. Create a contract with a specific IPN URL (see Configuring a separate IPN URL for a specific contract). For this contract, enter an invalid IPN URL. This will force BlueSnap to send an IPN error email with a copy of the IPN.

  4. Place a test order via the BuyNow checkout page for the contract you just set up.

  5. When the order is complete, BlueSnap will send an IPN. Because the IPN URL is invalid, BlueSnap copies the IPN to an email and sends it to the Admin email address you defined. You can then use this example IPN to parse each of the parameters and verify that they are configured correctly.

Back to Top

IPN (Webhook) Setup