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

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 endpoint to create a consumer user and through the Create Business User 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

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 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 event to verify a transaction sets the status of the transaction as CREATED. Transaction events can be used to updated 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 eventType that signals the status 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, by default status is set to CREATED. As the transaction is processed within your system, you can call the Create Transaction Event 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.