Invoice Callbacks

An IPN (Instant Payment Notification) is an HTTP POST message sent from the BitPay server to the merchant’s eCommerce server.

The primary purpose of an IPN is to alert the merchant’s ecommerce server that a BitPay invoice status has changed. Make sure to fetch the invoice status via BitPay's API before updating the order status on your server.

{ id: 'HxrCXSzVnoJhxeFGP6shNo',
  url: 'https://test.bitpay.com/invoice?id=HxrCfSzVeoJhxtFG36shNo',
  status: 'confirmed',
  btcPrice: '0.004371',
  price: 5,
  currency: 'EUR',
  invoiceTime: 1491831282376,
  expirationTime: 1491832182376,
  currentTime: 1491831443317,
  btcPaid: '0.004371',
  btcDue: '0.000000',
  rate: 1144.01,
  exceptionStatus: false,
  buyerFields: { buyerEmail: 'test@bitpay.com' } }

Please note that empty buyer fields are not included in the IPN.

When fullNotifications=true BitPay will send IPNs for invoice statuses paid, confirmed and complete. For more information about BitPay invoice states, please click here.

The BitPay server attempts to send IPNs multiple times until the send is either successful or the BitPay server gives up. The BitPay server attempts retries on the following schedule.

  • 0:00 - 1 minute delay
  • 1:00 - 4 minute delay
  • 5:00 - 9 minute delay
  • 14:00 - 16 minute delay
  • 30:00 - 25 minute delay
  • 55:00 - failed

The BitPay server considers a status code 200 response to be a successful send. The BitPay server does not follow redirects.

We would advise you to open a non-standard port and specify that port within the notificationURL instead of white listing BitPay IP addresses as they are subject to change without notice. Since BitPay does not sign IPNs they should not be trusted outright. We recommend using the IPN as a trigger to fetch the invoice status via BitPay's API.

IPN Troubleshooting

In the event that IPNs are not being received or processed as expected, please check the following:

  • Make sure that fullNotifications=true when creating the BitPay invoice.
  • Verify that your notificationURL for the invoice is https: (not http:)
  • Verify that your callback handler at the notificationURL is properly receiving POSTs. See this page how to manually test your notification URL.
  • Verify that the POST data received is properly parsed. See this page when getting blank IPNs using PHP.
  • Verify that your firewall is not blocking POSTs from servers it may not recognize.

IPNs can be resent by sending a POST to /invoices/:invoiceId/notifications accompanied by the token associated with the specified invoice.

Invoice States