API & SDK Documentation

Retrieve an Event Token

get https://test.bitpay.com/invoices//events

Retrieves a bus token which can be used to subscribe to invoice events.

Facades: merchant

Response

Name Type
facade
this indicates the facade used to fetch the event token for a given invoice. When the merchant facade is used, the BitPay server returns the event object for an invoice as seen from the merchant facade that is "merchant/invoice".
 string
data
invoices event data object
 object
url
base URL where you can subscribe to events (HTTP long polling)
 string
token
API token for subscriber resource, passed as ?token= query parameter value
 string
events
All supported &events[]= query parameter values. The possible values are:
  • payment - This allows you to be informed when the BitPay invoice reaches the status "paid", meaning the transaction has been applied to the invoice, but has not been confirmed yet. When listening to the websocket, this will be logged under the event: statechange. The invoice payload will contain the additional fields related to the merchant facade.
  • confirmation - This allows you to track the number of block confirmations for the transaction made to an invoice. When listening to the websocket, this will be logged under the event: statechange. The invoice payload will contain the additional fields related to the merchant facade.

 array
actions
All supported &action= query parameter values. Can be subscribe or unsubscribe.
 array

Subscribe to invoice events (HTTP long polling)

The "event bus" provides a real-time interface for API consumers to subscribe to changes that occur to a given resource. The bus implements HTTP long-polling and is compatible with the SSE (Server Sent Events) and EventSource specifications. API consumers need only a valid resource token retrieved from the existing REST API in order to subscribe.

In order to access an event stream via the bus, you have to request a "bus pass" for the resource to which you'd like to subscribe. These are special tokens that may only be used for receiving events via the bus. Bus passes are issued via API request. For example, to request a bus pass for a given invoice.

Once you have retrieved the bus pass, It's pretty simple. Send a GET request to the path configured for the bus - let's say it's bitpay.com/events including the appropriate parameters:

  • ?token= - your "bus pass" retrieved from the API
  • &action= - usually "subscribe", but options are provided in your bus pass
  • &events[]= - an array of events to listen for (also provided in the bus pass)

Once you've opened the connection, you'll want to listen for chunks of data to be passed to you. Each chunk represents an event. Since the bus adheres to the SSE/EventSource specification, chunks are passed back in the format:

event: <event_type>

data: {"some":"json"}

Type of Events

Browsers interpret the "event" property of each chunk and allow you to listen for it by adding an event listener directly to your EventSource instance. There are a few event types that the bus will expose:

  • connect - your request was valid and you are now subscribed to the resource
  • state - sent immediately following the connect event and contains the current state of the resource
  • statechange - sent whenever the resource changes and is published to the bus
  • error - something went wrong, you should close the connection and try again

See below an example of constructed URL which can be used to listen to invoice events. In this example, the invoice was paid via the BitPay wallet from a desktop.

As this "bus pass" was retrieved using the merchant facade https://bitpay.com/events?token=4MuqDPt93i9Xbf8SnAPniwbGeNLW8A3ScgAmukFMgFUFRqTLuuhVdAFfePPysVqL2P&action=subscribe&events[]=payment&events[]=confirmation

Language