Inflight transactions
Overview
Inflight, inflight, is a transaction parameter that instructs Blnk to hold on applying a transaction until a condition has been met. This condition could be confirming that it has been processed in real life by your payment partners or custom conditions set by your application.
Before you continue, learn more about transaction workflows → Transaction workflows.
This is very useful for transactions that may take a while to complete. It also makes sure that funds are not available for a balance to spend until the transaction has actually happened, and you no longer have to always initiate a refund when your partners return a failed response.
How Inflight transactions works
When you enable inflight on your transactions, the workflow becomes slightly different from the default way a transaction is recorded.
In this section, you’ll learn the step-by-step process of how Blnk works when you enable inflight on a transaction.
Before the conditions are met
When you record a new transaction, it’s added to the transaction queue by default. Once it is ready for processing, the transaction status is updated to INFLIGHT and three new sub-balances are created within the balances specified in the source and destination fields.
inflight_credit_balance: Total amount of money waiting to be credited.inflight_debit_balance: Total amount of money waiting to be debited.
While the transaction is in INFLIGHT, the amount is debited from the source’s inflight_debit_balance and credited into the destination’s inflight_credit_balance. The balances of the source and destination remain untouched.
Why inflight balances? The transaction has not been applied, so the balances of the source and destination cannot be affected yet. Inflight balances exist to help you keep track of the amounts yet to be debited or credited to a balance.
When a transaction is
INFLIGHT, it is advised to ensure that the source balance has enough funds to complete the transaction once it moves to the next change. We encourage to do balance checks and prevent the source balance from having a balance lower than the amount in itsinflight_debit_balance.
In the example above, USD 50 is being sent. Because inflight is enabled, the amount was debited from the source’s inflight_debit_balance instead of the source itself, and credited to the destination’s inflight_credit_balance instead of the destination itself.
After the conditions are met
Once the conditions are met, Blnk expects one of two instructions — commit or void.
Commit: Instructs Blnk to continue with the transaction and apply it to the balances. This debits thesourceand credits the source’sinflight_debit_balance; and debits the destination’sinflight_credit_balanceand credits thedestination.Void: Instructs Blnk to stop and void the transaction. This refunds the transaction between both inflight balances, and nothing else needs to be done.
Calculating balances when Inflight is applied
When a transaction is inflight, the balances of the source and destination are not updated until you have committed the transaction.
Blnk records the amount being held in inflight in Inflight balances. Each ledger balance is assigned an inflight_credit_balance and an inflight_debit_balance.
It is important to make sure the amount being held in inflight is available in the ledger balance. If not, any commit instruction will be rejected.
The best way to do this, within your application, is to prevent your user from having access to the amount being held in inflight. To do this:
balance- Total balance of the ledger balance.inflight_credit_balance- Total amount waiting to be added to your balance.inflight_debit_balance- Total amount waiting to be deducted from your balance.available_balance- Total amount accessible by your user (balance-inflight_debit_balance). This is computed by you in your application
Applying inflight to transactions
Initiate a transaction
Send a request to the Record Transaction endpoint and input the required fields. Include "inflight": true to enable Inflight for the transaction.
{
"amount": 750000,
"precision": 100,
"reference": "ref_001adcfgf",
"currency": "USD",
"source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
"destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
"description": "For fees",
"inflight": true,
"inflight_expiry_date": "2024-02-03 12:38:19"
}
inflight_expiry_datedefines when this transaction should expire if it hasn’t be committed or voided yet.
To disable Inflight, remove the inflight field from your request payload.
Transaction is added to queue for processing
The transaction is immediately added to a queue for processing with its status initially set to QUEUED.
Once it is ready to be processed, the status is updated to INFLIGHT and a transaction.inflight webhook event is sent to notify you. The transaction record is held in INFLIGHT until you instruct Blnk with the next steps. To check for the current transaction status, you can search by reference or transaction_id and you’ll see the following:
{
"transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
"source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
"destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
"reference": "ref_001adcfgf",
"parent_transaction": "",
"amount": 750,
"precise_amount": 75000,
"rate": 0,
"precision": 0,
"currency": "USD",
"description": "For fees",
"hash": "032af5e26c8a2c2690f1bb70bdd7c044bbdf9c7f5576fc0f693200baf65a9ee3",
"allow_overdraft": false,
"status": "INFLIGHT",
"created_at": "2024-02-20 05:28:03 UTC",
"scheduled_for": "0001-01-01T00:00:00Z",
"inflight_expiry_date": "0001-01-01T00:00:00Z"
}
When a transaction is INFLIGHT, the amount is not yet applied to the participating balances.
Instruct Blnk what to do next
Once the condition is met, call the Inflight endpoint URL and instruct what you want Blnk to do with the transaction.
{
"status": "commit"
}
| Field | Description | Required? | Type |
|---|---|---|---|
status | Instruction to Blnk depending on if the condition has been met. Send commit if you want Blnk to apply the transaction to the balances OR void if it should be discarded. | Yes | String |
✅ — If asked to 'commit':
Blnk creates a new transaction record with the details of the INFLIGHT transaction and applies it to the balances. The source’s inflight_debit_balance and destination’s inflight_credit_balance are reset, and the money moves from the source to the destination.
You can also choose to commit in bits, i.e., you can instruct Blnk to release the held funds in bits. To do this, pass an amount field in your inflight request payload like this:
{
"status": "commit",
"amount": 1000
}
- Make sure the amount being passed is less than or equal to the amount being held in
INFLIGHT. - You can commit as many as times as you want as long as the sum of the amounts of each commit is less than or equal to the amount being held in
INFLIGHTfor that particular transaction.
❌ — If asked to 'void':
If voided, Blnk also creates a new transaction record with the details of the INFLIGHT transaction. However, this time, the status will be VOID; it is not applied to any of the balances, and the source’s inflight_debit_balance and destination’s inflight_credit_balance are reset.
You cannot void in bits.
Inflight statuses
There are three total inflight statuses you can send in the payload. Please note, an inflight status is different from a transaction status. A status field represents the instruction given to Blnk to apply to the transaction.
-
commit: This means the inflight conditions have been met and the transaction should be applied to its balances. -
void: This means the inflight conditions were not met and the transaction should be discarded. -
expired: This means the transaction stayed in theINFLIGHTstatus past the specified expiry date. If an inflight transaction expires, a new transaction record is created with its status saved asEXPIREDand the transaction is discarded.
Use cases
Inflight is best used when a balance in your Blnk Ledger is the source and your application has little control over how the transaction actually happens in real life. This means transactions between balances in your Blnk Ledger do not need to have inflight enabled.
Useful applications for inflight include:
- For managing KYC limits: When an account crosses its KYC limits determined by your application, you can hold all deposits with inflight until the user’s KYC is updated.
- For escrow: Inflight allows you to easily implement escrow features in your application, allowing your users see the amount being held (but not available to them to spend).
- For card payouts: Hold amounts in an inflight balance until the card is authorized by the payment processor for successful payment.
- For external payouts: Hold amount in an inflight balance while your payout is being processed by your provider; only release it when the transaction is successful or failed.
See also
Setting up internal balances
Learn how to set up internal balances
Understanding precision
Improve the correctness of your ledger
Handling concurrency
How Blnk queues transactions
Managing notifications
Set up how you receive notifications
Need help?
Are you stuck? Do you have a question that isn’t answered in this doc? Have you run into a problem you can’t solve? Want to file a bug report?
Join our Discord server and share your questions/thoughts with other developers building financial applications like you.
Was this page helpful?