Skip to main content
Available in version 0.6.0 and later.
An inflight transaction reserves funds until you commit or void it. When you set inflight: true, Blnk tracks pending amounts in separate inflight balance fields while your settled balances stay unchanged. Use inflight when you need authorization, verification, or external confirmation before applying a transfer. Blnk, by default, includes inflight debit amounts (money reserved to be deducted from the source balance) when checking available funds on the source balance (balance - inflight_debit_balance). See Managing insufficient funds.

​
Use cases

Useful applications for inflight include:
  • KYC limits: Hold deposits inflight until the user’s KYC tier is updated.
  • Escrow: Show users an amount being held without making it spendable.
  • Card payouts: Hold funds until the payment processor authorizes the charge.
  • External payouts: Hold funds while a provider processes the payout; commit or void based on the outcome.

​
Create an inflight transaction

1

Create an inflight transaction request

Set inflight: true on a standard Create transaction request:
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/transactions" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 10000,
    "precision": 100,
    "reference": "ref_001adcfgf",
    "currency": "USD",
    "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
    "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "description": "For vacation",
    "inflight": true
  }'
201 Created
{
  "amount": 100,
  "transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
  "status": "INFLIGHT",
  "inflight": true,
  "created_at": "2024-12-21T01:36:46.997063436Z"
}
With the default queue enabled, Blnk first records the transaction as QUEUED, then moves it to INFLIGHT when the worker processes it. See Transaction lifecycle.
2

Track inflight balances

Blnk tracks pending inflight amounts with three fields on each balance. For the full list of balance parameters, see Balance parameters.
inflight_credit_balance: Pending credits awaiting processing
inflight_debit_balance:  Pending debits awaiting processing
inflight_balance:        inflight (credit - debit)
How a transaction is processed in inflight
For example: consider an inflight transaction where $100 is transferred from balance_A to balance_B:
Initial State:
balance_A: $200 available funds
balance_B: $0 available funds

Transaction Amount: $100
balance_idMain balanceInflight balanceInflight creditInflight debit
balance_A200-1000100
balance_B01001000
In this scenario:
  • balance_A shows a negative inflight balance (-100) because funds are pending outflow.
  • balance_B shows a positive inflight balance (100) because funds are pending inflow.
The main balances remain unchanged until you commit or void the inflight transaction.

Commit & void inflight

Commit, void, or verify your inflight transaction.

​
Error handling

Structured errors are available from Blnk Core 0.15.0 and later.
Create transaction returns 400 when the request body fails validation before Blnk records an inflight transaction.
CodeWhen it happens
TXN_VALIDATION_ERRORRequired fields are missing or invalid (for example both amount and precise_amount).
GEN_MALFORMED_REQUESTThe JSON body is malformed or exceeds the request size limit.
400 Bad Request
{
  "error_detail": {
    "code": "TXN_VALIDATION_ERROR",
    "message": "amount: cannot be blank."
  },
  "errors": "amount: cannot be blank."
}
To resolve the error:
CodeWhat to do
TXN_VALIDATION_ERRORFix the field named in the error message. See Create transaction.
GEN_MALFORMED_REQUESTCheck JSON syntax and request size limits in Server security.
When the source balance has insufficient funds, Blnk records a REJECTED transaction instead of returning an HTTP error. See Managing insufficient funds. Commit and void errors are covered in Commit & void inflight — Error handling. See API error codes for the full catalogue.

Commit & void inflight

Commit, void, and verify inflight transactions.

Bulk commit & void

Commit or void many inflight transactions at once.

Inflight for multiple sources & destinations

Inflight across multiple sources or destinations.

Transaction lifecycle

Statuses from creation through completion.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.