> This page is for version FRAML API (default).
> For other versions, use one of these documentation indexes:
> - FRAML API (default): https://docs.flagright.com/framl-api/llms.txt
> - Management API: https://docs.flagright.com/management-api/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.flagright.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.flagright.com/_mcp/server.

Flagright's core API is made up of three entities.

#### [Users](/guides/overview/entities#user)

#### [Transactions](/guides/overview/entities#transaction)

#### [Transaction Events](/guides/overview/entities#transaction-event)

\
\


# User

This is an object representing a User that partakes in a transaction within your
system. A User can be of type Business or Consumer. A consumer user is a
individual that uses your product. Business users pertains to business using
your services that result in a payment transaction.

For each user within your system, you send the user payload (KYC data and other
user data) to the Flagright API through the
[Create Consumer User](/api-reference/api-reference/consumer-users/create)
endpoint to create a consumer user and through the
[Create Business User](/api-reference/api-reference/business-users/create)
endpoint to create a business user. You can call the API whenever there's a new
user on your system or whenever a user updates their info on your system.

Each User is associated with a unique `userId`. You can pass in the internal
`userId` along with your request and use that ID to query the user.

# Transaction

This is an object representing a Transaction within your system. On a high level, transaction
is any event that results value (e.g. money) moving from one place to another. A transaction
encapsulates value movement between different or same payment modes. This can be money moving
from from a bank account to a digital wallet (DEPOSIT), money moving between two wallets, money
moving from a wallet to a bank (withdrawal) or from one card to another.

The transaction entity primarily contains timestamp (UNIX timestamps in ms),
data on ID of the user entity that is taking part in the transaction, origin &
destination amounts and origin & destination payment details. The transaction
entity has also other optional fields such as transaction type, device metadata
etc -
[full payload](/api-reference/api-reference/transactions/verify)

Each transaction is associated with a unique *transactionId*. You can pass in
the internal `transactionId` along with your request and use that ID to query
transaction. If no `transactionId` is provided, the Flagright system will create
one for the transaction. It's usually a good idea to store this ID internally in
case you need to retrieve it at a later stage.

For every transaction within your system, you send the transaction payload to
Flagright API through the
[Verify Transaction](/api-reference/api-reference/transactions/verify)
endpoint, to verify whether the transaction is safe to process.

# Transaction Event

Transaction Event entity encapsulates all the events that pertain to a
transaction. The events generally pertain to a state change with respect to the
status of the transaction. By default, calling the
[Verify Transaction](/api-reference/api-reference/transactions/verify) event to verify
a transaction sets the status of the transaction as `CREATED`.
Transaction events can be used to update the status of the transaction and to
provide additional data surrounding the transaction in its lifecycle.

Each transaction event must have an associated transaction - referenced in the
payload through `transactionId`. In addition, transaction event must also
contain `transactionState` that signals the state of the transaction and timestamp
(UNIX timestamp in ms) of when the transaction event occurred.

### Transaction Lifecycle through Transaction Events

In case you want to manage the transaction lifecycle - from `CREATED` to
`SUCCESSFUL` - you can do so using transaction events. You do not need to manage
this lifecycle and status if you want to use the transaction verification
endpoint as a single idempotent request to check the transaction. The
transaction status is transparent in our interface and is exposed only through
transaction events for more sophisticated use cases.

When a transaction payload is passed to
[Verify Transaction](/api-reference/api-reference/transactions/verify),
by default status is set to `CREATED`. As the transaction is processed within
your system, you can call the
[Create Transaction Event](/api-reference/api-reference/transaction-events/create)
endpoint to update the status of the transaction and provide additional data
that resulted in status change. This status change will be reflected in the
console for your operational teams to see.