API BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesBlueSnap.com
Top of Section

IPNs (Webhooks)

Learn how you can use Instant Payment Notifications (IPNs) to get real-time information about transaction events

IPNs provide an effective way to keep you up-to-date on all transaction events in real time. Transaction events include actions like authorizations, payments, refunds and more.

Whenever one of these events occurs, the IPN will provide you with basic details about the event, such as the price, product, shipping address details, payment method, and shopper information.

📘

IPNs and Webhooks

Some payment processors use the term Webhooks when referring to notifications. Webhooks and IPNs are essentially equivalent.

What IPNs are used for

Here are some ways you might use IPNs:

  • Make sure your accounting records are updated when a payment is made
  • Take action when a chargeback is processed
  • Send a subscription reminder email to a customer when their subscription is due for renewal
  • Update your customer database when a subscription is processed

How and when BlueSnap sends IPNs

IPNs are automatically transmitted via an HTTP POST request to a unique URL on your site's server, which you will define. IPNs are triggered by an event such as an authorization, payment acceptance, or refund confirmation and are sent as soon as the event is complete. Refer to IPN FAQs.

How to manage IPNs using the Merchant Portal

To enable IPNs, you need to set up a server and URL on your side and then configure IPNs in your BlueSnap account. Refer to Setting up IPNs.

How to manage IPNs using our API

We also offer APIs to retrieve IPN configuration information, enable/disable IPNs, or delete all IPN configurations for a user.

Request Content

      ipnDestinations     object    required
     ipnUrl     string    required
     ensureNotificationReceipt     string    required
     receiveAffiliateNotifications     string    required

Retrieve IPN Configuration

Retrieve the current IPN settings using this request.

curl -L -X GET 'https://sandbox.bluesnap.com/services/2/notification-config/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'bluesnap-version: 2.0' \
-H 'Authorization: Basic QVBJXzE2MTk2MjgyMzU0ODkyMDM5MTMzODc0OkhvYmJpdHkyMSE=' \
Enable/Disable IPNS

Use this request to enable or disable specific IPN types, as well as the ensureNotificationReceipt and receiveAffiliateNotifications settings.

In the body of the request, include JSON or XML representing your desired notification configuration for the authorized user. You can set each IPN type to true to enable or false to disable. Fields that are not explicitly sent in the request body will be set to false by default.

Note that the ipnURL field is required. You may use a third party webhook site like https://webhook.site/ to generate an ipnURL. 

curl -L -X POST 'https://sandbox.bluesnap.com/services/2/notification-config/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic QVBJXzE2MTk2MjgyMzU0ODkyMDM5MTMzODc0OkhvYmJpdHkyMSE=' \
-d '
{
    "ipnDestinations": [
        {
            "ipnUrl": "https://webhook.site/2560e9b0-c46c-4a48-9333-0f9108e74348",
            "sendAuthOnly": true,
            "sendCancellation": true,
            "sendCancelOnRenewal": true,
            "sendCharge": true,
            "sendChargeback": true,
            "sendChargebackStatusChanged": true,
            "sendContractChange": false,
            "sendCancellationRefund": true,
            "sendFailedPayoutTransfer": false,
            "sendSubscriptionReminder": true,
            "sendDecline": true,
            "sendRefund": true,
            "sendRecurring": false,
            "sendCcFailure": true,
            "sendSubCcFailure": true,
            "sendUnderVendorReview": true,
            "sendPaymentUpdate": true,
            "sendPaymentUpdateFailure": true,
            "sendAccountUpdater": true,
            "sendPayout": true,
            "sendVendorStatusChanged": true,
            "sendFraudDecline": true,
            "sendChargePending": true,
            "sendShopperDeleted": true,
            "sendVendorReportAvailable": true,
            "sendMerchantOnboarded": true,
            "sendOfflineOrder": true,
            "sendCcStatusChanged": false
        }
    ],
    "ensureNotificationReceipt": false,
    "receiveAffiliateNotifications": true
}'
Delete All IPN Configurations

Use this request to remove all IPN destinations and configurations associated with the authorized user. 

curl -L -X DELETE 'https://sandbox.bluesnap.com/services/2/notification-config/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'bluesnap-version: 2.0' \
-H 'Authorization: Basic QVBJXzE2MTk2MjgyMzU0ODkyMDM5MTMzODc0OkhvYmJpdHkyMSE=' \

Available IPN Types

BlueSnap provides IPNs to all merchants for various event types, such as a charge, authorization only, an offline order or failed credit card charge. See All IPNs Name Reference for a complete list of available IPNs and detailed information about each one.

For details about all IPN parameters, Refer to IPN parameter reference.

Example IPN

An IPN is a long string of text with fields and attributes that contain information about the transaction. For example:

invoiceCountry=US&invoiceZipCode=&invoiceFirstName=Joe&invoiceFaxNumber=&invoiceState=OR&invoiceAddress2=&invoiceEmail=emil.ray%40bluesnap.com&invoiceLastName=Shopper&invoiceAddress1=&invoiceCompany=&invoiceCity=&invoiceExtension=&invoiceMobilePhone=&invoiceWorkPhone=&invoiceTitle=&lastName=Shopper&country=US&zipCode=&extension=&address2=&city=&address1=&homePhone=&title=&accountId=20626979&firstName=Joe&mobilePhone=&faxNumber=&company=&workPhone=&state=OR&email=emil.ray%40bluesnap.com&username=1447774446472887319554743963741&shippingCity=&shippingLastName=Shopper&shippingCountry=US&shippingZipCode=&shippingMethod=&shippingFirstName=Joe&shippingState=OR&shippingAddress2=&shippingAddress1=&overridePrice=0.00&invoiceAmount=30.00&language=ENGLISH&creditCardType=VISA&invoiceAmountUSD=30.00&templateId=91&productName=My+Awesome+Game&creditCardExpDate=1%2F2016&contractOwner=500801&referenceNumber=1011310133&contractName=Nintendo+Version&currency=USD&invoiceInfoURL=https%3A%2F%2Fsandbox.bluesnap.com%2Fjsp%2Forder_locator_info.jsp%3FrefId%3DDB24C79E3E449AB09A1936EF6F020625%26acd%3D80FD091BA5366B75&remoteAddress=50.207.189.243&contractChargePrice=30.00&quantity=1&productId=404141&invoiceChargeCurrency=USD&cardSubType=CREDIT&invoiceChargeAmount=30.00&referrer=&contractPrice=30.00&creditCardLastFourDigits=1111&testMode=N&contractId=2269035&addCD=N&untilDate=11%2F17%2F2015+07%3A34+AM&paymentMethod=CC&paymentType=CC&invoiceLocalAmount=30.00&invoiceURL=https%3A%2F%2Fsandbox.bluesnap.com%2Fjsp%2Fshow_invoice.jsp%3Fref%3DDB24C79E3E449AB09A1936EF6F020625&shopperOrderUrl=https%3A%2F%2Fsandbox.bluesnap.com%2Fjsp%2Forder_locator_info.jsp%3FrefId%3DDB24C79E3E449AB09A1936EF6F020625%26acd%3D80FD091BA5366B75&originalRequestUrl=&contractLocalPrice=30.00&shopperAdminUrl=https%3A%2F%2Fsandbox.bluesnap.com%2Fjsp%2Forder_locator_info.jsp%3FrefId%3DDB24C79E3E449AB09A1936EF6F020625%26acd%3D80FD091BA5366B75&invoiceLocalCurrency=USD&recurringDisclaimer=N&targetBalance=BLUESNAP_ACCOUNT&promoteContractsNum=0&EDWPeriod=&EDWSurcharge=&EDWAmountUSD=&EDWContractId=&EDWSurchargeUSD=&EDWAmount=&vatId=&taxAmountUSD=0.00&taxRate=&taxChargeAmount=0.00&authKey=&transactionType=CHARGE&bluesnapNode=99&plimusNode=99&couponCode=&licenseKey=Licensing+information+will+be+sent+to+you+shortly.&cvvSent=Y&avsSent=N&cvvResponse=Not+processed+&avsResponse=Issuer+unavailable+or+AVS+not+supported+%28US+Issuer%29+&transactionDate=11%2F17%2F2015+07%3A34+AM

lastName=Doe&country=US&zipCode=30328&extension=52&address2=&city=Atlanta&address1=760+MT+VERNON+HIGHWAY+NE+%2CATLANTA+GA+30328&homePhone=&title=&accountId=19589706&firstName=Jhone&mobilePhone=&faxNumber=&company=&workPhone=0523584124&state=AL&email=jhonedoe%40gmail.com&username=1471869314641&invoiceCountry=US&invoiceZipCode=30328&invoiceFirstName=Shaul+Cohen+OR+Alon&invoiceFaxNumber=&invoiceState=AL&invoiceAddress2=&invoiceEmail=jhonedoe%40gmail.com&invoiceLastName=Yosef&invoiceAddress1=760+MT+VERNON+HIGHWAY+NE+%2CATLANTA+GA+30328&invoiceCompany=&invoiceCity=Atlanta&invoiceExtension=52&invoiceMobilePhone=&invoiceWorkPhone=0523584124&invoiceTitle=&shippingCity=Atlanta&shippingLastName=Yosef&shippingCountry=US&shippingZipCode=30328&shippingMethod=&shippingFirstName=Jhone&shippingState=AL&shippingAddress2=&shippingAddress1=760+MT+VERNON+HIGHWAY+NE+%2CATLANTA+GA+30328&invoiceAmount=2.00&language=ENGLISH&creditCardType=VISA&cardSubType=DEBIT&cardCategory=PEONY&invoiceAmountUSD=2.00&productName=testProduct&paymentType=&creditCardExpDate=&contractOwner=399928&referenceNumber=38528358&contractName=Subscription+contract+2&currency=USD&cancelReason=test&invoiceInfoURL=https%3A%2F%2Fshoppers.bluesnap.com%2Fjsp%2Forder_locator_info.jsp%3FrefId%3DEBBE554ECE528D63%26acd%3DEBEDCB01BBF0320D&remoteAddress=0%3A0%3A0%3A0%3A0%3A0%3A0%3A1&quantity=1&productId=310592&invoiceChargeCurrency=USD&invoiceChargeAmount=2.00&originalRefNum=38528358&transactionType=CANCELLATION&referrer=&creditCardLastFourDigits=&testMode=N&contractId=2186556&paymentMethod=&subscriptionId=39546714&addCD=N&untilDate=08%2F29%2F2016+06%3A06+AM&authKey=4df72f8c802a6caf5b0e3e4439cfb891&targetBalance=BLUESNAP_ACCOUNT&taxAmountUSD=0.00&taxRate=&taxChargeAmount=0.00&vatId=&Color=Green&cancelledContractId=2186556&shippingMethod=&shopperOrderUrl=https%3A%2F%2Fshoppers.bluesnap.com%2Fjsp%2Forder_locator_info.jsp%3FrefId%3DEBBE554ECE528D63%26acd%3DEBEDCB01BBF0320D&templateId=2&licenseKey=&promoteContractsNum=0&bluesnapNode=1&plimusNode=1&couponCode=&transactionDate=08%2F22%2F2016+04%3A10+PM&merchantTransactionId=&vendorId=11111&vendorName=vendor+name+test