Events

Events API provides a way to listen for events of interest as they relate to your program. For example, you may want to listen for Account status changes or Transactions as they occur.

There are two approaches to consume events, traditional poll request and event streaming using Server-Sent Events. You might first want to consider the approach that best suits your architecture.

Poll Events

A standard request to GET /events will trigger the polling mechanism to fetch events based on the filters provided. This is standard request/response flow. The endpoint will hold the connection until either event(s) are returned or a timeout has occurred. The timeout is random but is at a maximum 1-minute long.

The response will contain the last_sequence_number in the event list which can be used in a subsequent request.

GET /events

Response:

{
  "data": [
    {
      "id": "c773c2bb-be73-4400-889c-df823ebc849e",
      "program_id": "cf2d36e4-68cc-4b10-9dd5-17ac5e07d60f",
      "sequence_number": 1,
      "created_dt": "2022-01-02T03:04:05.123456-05:00",
      "type": "ACCOUNT_STATUS",
      "data": {
        "account_id": "2c52e04d-9688-4b9c-be4a-87468b2cb2e8",
        "blockchain_address": "tp180pfr6g45upsrta04l2xd8v08x9jntljgx0gzu",
        "status": "PENDING"
      }
    }
  ],
  "last_sequence_number": 1,
  "limit": 100
}

Stream Events

Using the event stream endpoint, you can listen for events as they unfold in real-time. The endpoint returns events matching the criteria provided and sends events using the Server-Sent Events (SSE) standard once a connection has been established. This requires setting the Accept header to text/event-stream.

Sample CURL Request

curl -X GET https://api.pay.test.figure.com/events/stream \
-H 'Accept: text/event-stream' \
-H 'Authorization: Bearer <access_token>'

Response

id: 1
data: [{"id":"c773c2bb-be73-4400-889c-df823ebc849e","type":"ACCOUNT_STATUS","program_id":"cf2d36e4-68cc-4b10-9dd5-17ac5e07d60f","sequence_number":"1","created_dt":"2022-01-02T03:04:05.123456-05:00","data":{"type":"account_status","account_id":"2c52e04d-9688-4b9c-be4a-87468b2cb2e8","blockchain_address":"tp180pfr6g45upsrta04l2xd8v08x9jntljgx0gzu","status":"PENDING"}}]

Here the id is treated as the last_sequence_number. If the connection fails or is complete, you can use this to set your starting point.

Retrieve a single event

Fetch a single event by either its id or sequence_number for the authenticated program.

GET /event/:id

GET /event/sequence/:sequence_number

Event Types

Every event has a data field with contents related to the specific event type. This is a list of all current event types. Note: This list is subject to be updated as more types may be added

Type	Description
account_status	Account status change
transaction	A transaction was created between accounts

Account Status

Name	Description
account_id	Unique identifier for this account
blockchain_address	Blockchain address for this account
status	The new status for this account - PENDING, OPEN, FROZEN, or CLOSED

Transaction

Name	Description
transaction_id	Unique identifier for this transaction
from_address	The blockchain address of the sender
to_address	The blockchain address of the recipient
amount	Amount of coin sent in USD Pennies
type	Type of this transaction see below
status	Status of this transaction - PENDING, COMPLETE, ERROR
network_fee	The blockchain network fee
note	Contains additional details about the transaction i.e. merchant name, bank name, etc
card_id	For card transactions, the unique identifier of the card used
created_dt	Creation time of this transaction
updated_dt	Most recently updated time of this transaction

Transaction Types

Type	Description
card	Debit card transaction once cleared
fee	Blockchain network fee
inbound	Inbound ACH transfer from external bank account to account
intra	Inter-account/program transaction such as Peer-to-Peer
outbound	Outbound ACH transfer from account to external bank account
system	Transactions made by the system account