Skip to main content

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

TypeDescription
account_statusAccount status change
transactionA transaction was created between accounts

Account Status

NameDescription
account_idUnique identifier for this account
blockchain_addressBlockchain address for this account
statusThe new status for this account - PENDING, OPEN, FROZEN, or CLOSED

Transaction

NameDescription
transaction_idUnique identifier for this transaction
from_addressThe blockchain address of the sender
to_addressThe blockchain address of the recipient
amountAmount of coin sent in USD Pennies
typeType of this transaction see below
statusStatus of this transaction - PENDING, COMPLETE, ERROR
network_feeThe blockchain network fee
noteContains additional details about the transaction i.e. merchant name, bank name, etc
card_idFor card transactions, the unique identifier of the card used
created_dtCreation time of this transaction
updated_dtMost recently updated time of this transaction

Transaction Types

TypeDescription
cardDebit card transaction once cleared
feeBlockchain network fee
inboundInbound ACH transfer from external bank account to account
intraInter-account/program transaction such as Peer-to-Peer
outboundOutbound ACH transfer from account to external bank account
systemTransactions made by the system account