Testing your notification URL manually by sending IPNs with cURL

Problem:

• You are not receiving Instant Payment Notification (IPN) messages at the location specified in the notificationURL parameter or you would like to manually test how your application handles IPN messages.

Solution:

Instant Payment Notifications (IPNs) are sent from Bitpay upon every invoice status change if you have set the fullNotifications parameter to true.  IPNs are POSTed to your notification URL specified when you created the invoice.  If the gateway receives an

HTTP/1.1 200 OK

response from your server, the message is deemed to have been correctly delivered.

NOTE: This does not mean your application correctly handled the data - only that it was received successfully by your server!

If an HTTP error code is received by the gateway, it will attempt to resend the IPN at increasing time intervals.  If this is happening, check your invoice creation request to ensure you are sending the correct parameter for notification URL.  Also check that your fullNotifications parameter is set to true.

The content header for the POST request should be

Content-Type: application/json

and the body of the HTTP POST request should be a JSON-formatted string with this structure (spacing has been added for readability):

    {
        "id":"1234567890",
        "url":"https://bitpay.com/invoice?id=xxxxxxxxxx",
        "posData":"{\"id\":\"1234567890\"}",
        "status":"complete",
        "btcPrice":"0.00",
        "price":0.0000,
        "currency":"USD",
        "invoiceTime":1111111111111,
        "expirationTime":1111111111111,
        "currentTime":1111111111111,
        "btcPaid":"0.0000",
        "rate":1,
        "exceptionStatus":false,
        "buyerFields":
            {
                "buyerName":"Some Customer",
                "buyerAddress1":"123 Main St.",
                "buyerAddress2":"Apt 123",
                "buyerCity":"Atlanta",
                "buyerState":"GA",
                "buyerZip":"30303",
                "buyerEmail":"customer@somedomain"
            }
    }

Note: You may wish to substitute values shown above with data that more closely matches your test requirements.

For Linux and Mac OS users, open a terminal/shell and use this command to manually send a test IPN using the curl utility:

curl --no-keepalive --raw --show-error --verbose --connect-timeout 10 --insecure --max-redirs 1 -H "Content-Type: application/json" -d '{your JSON IPN test data}' https://your.ipn.handler

The response from the curl command should look something similar to this:

* Hostname was NOT found in DNS cache
*   Trying [the IP address of your server]...
* Connected to [the IP address of your server] port 443 (#0)
> POST /path/to/your/ipnhandler HTTP/1.1
> User-Agent: curl/7.37.1
> Host: [the IP address of your server]
> Accept: */*
> Content-Type: application/json
> Content-Length: [length of your JSON string]
> 
* upload completely sent off: [x] out of [y] bytes
< HTTP/1.1 200 OK
< Date: Wed, 19 Nov 2014 17:36:50 GMT
* Server [your server software] is not blacklisted
< Server: [your server software]
< Content-Length: 0
< Connection: close
< Content-Type: text/html; charset=UTF-8
< 
* Closing connection 0

A successful response will have the 200 response code.  If you receive any other HTTP codes, there is a problem with your webserver or your IPN handling application.

Affects:

• All developers and merchants wishing to diagnose IPN issues or to test how an existing application handles IPN messages from Bitpay.