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 |