API & SDK Documentation

Notifications (IPN)

Webhooks

Webhooks are an HTTP POST message sent from the BitPay server to the merchant’s eCommerce server.

Instant Payment Notifications

The only webhook available at the moment is the Instant Payment Notification (IPN). The primary purpose of an IPN is to alert the merchant’s ecommerce server that the status of a resource (invoice, payout) has changed. The messages are sent to the notificationURL field when creating the invoice or payout.

Handling

❗

BitPay does not sign IPNs, so the information in the payload should never be trusted outright

  1. The IPN shall be used as a trigger to verify the status of a specific invoice or payout. This can be done by fetching the corresponding invoice or payout, since both invoice id and payout id are provided in the body of the IPN.
  2. The invoice status paid does not represent a payment guarantee, so merchants should only mark an order as successful once the corresponding BitPay invoice has reached the status confirmed or complete.
  3. Merchants who rely on the invoice status confirmed to fulfill orders also have to monitor IPNs for the complete status, as in some cases the IPN for the status "confirmed" may not be sent (for instance: node outage or network errors).
  4. The BitPay server expects an HTTP 200 response with an empty body. Any other HTTP response is considered by BitPay as a failed delivery. The BitPay server attempts to send IPNs multiple times until the send is either successful or the BitPay server gives up.
  5. Make sure to not rely on whitelisting BitPay’s sending IP addresses, as these IP addresses are subject to change without notice.
  6. Make sure to use HTTPS for your notificationURL.

Notification Types