Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt

Use this file to discover all available pages before exploring further.

Available in version 0.6.0 and later.
An inflight transaction keeps your transaction on hold until you take further action. When enabled using the inflight parameter, transactions follow a specialized workflow that maintains separate balances for pending operations. It is best used when you want to wait for feedback or authorization before a transaction is applied in your ledger.

​
Before we start,

Remember that all ledger balances in Blnk have 6 main balance parameters:
  1. balance: This shows the current value held in the ledger balance.
  2. credit_balance: This is the total sum of all amounts received by a ledger balance.
  3. debit_balance: This is the total sum of all amounts sent by a ledger balance.
  4. inflight_balance: This shows the net amount held inflight for a balance.
  5. inflight_credit_balance: This is the total sum of all amount waiting to be received by a ledger balance.
  6. inflight_debit_balance: This is the total sum of all amount waiting to be deducted from a ledger balance.

​
How Inflight works

This is how inflight transactions work in Blnk:
1

Record transaction with Inflight

First, specify that the transaction should be held inflight by setting inflight: true.
Record inflight
{
    "amount": 100,
    "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
}
When recording a new transaction with Inflight, the system, by default, will:
  1. Initializes the transaction in the QUEUED state.
  2. Processes and moves the transaction to INFLIGHT.
  3. Maintains the original balances while tracking the pending amounts in inflight balance parameters.
2

Balance management

Next, understand how Blnk tracks inflight amounts. We use these three balance parameters:
inflight_credit_balance: Pending credits awaiting processing
inflight_debit_balance:  Pending debits awaiting processing
inflight_balance:        inflight (credit - debit)
Step 1: How a transaction is processed in InflightFor 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 the transaction is committed.
3

Updating Inflight

Updating an inflight transaction means telling Blnk what to do with it next: commit or void?To update an inflight transaction, use the Update Inflight endpoint:Scenarios when inflight transactions are finished processing
PUT /transactions/inflight/{transaction_id}
  1. Indicates transaction conditions are met.
  2. Triggers balance updates, and clears the inflight balances.
  3. Creates new transaction record with APPLIED status.
cURL
curl -X PUT http://localhost:5001/transactions/inflight/{transaction_id} \
  -H 'X-Blnk-Key: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "commit"
  }'
In our example, after commit:
balance_idMain balanceInflight balanceInflight creditInflight debit
balance_A100000
balance_B100000

​
Bulk inflight updates

Available in version 0.14.2 and later.
Use the bulk inflight endpoints when you need to commit or void multiple independently-created inflight transactions in one request.
Bulk inflight updates are for independently-created inflight transactions. For inflight transactions created through the bulk transaction API, use the batch update flow in Bulk transactions.
cURL
curl -X POST http://localhost:5001/transactions/inflight/bulk/commit \
  -H 'X-Blnk-Key: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "transactions": [
      { "transaction_id": "txn_11111111-1111-4111-8111-111111111111" },
      {
        "transaction_id": "txn_22222222-2222-4222-8222-222222222222",
        "amount": 40
      }
    ]
  }'
Bulk requests accept up to 100 items. Each item is processed independently and the response includes succeeded, failed, and a results array with each transaction’s status. See also: Bulk commit inflight and Bulk void inflight.

​
Schedule inflight commits

Available in version 0.14.1 and later.
When you create an inflight transaction, Blnk reserves the balance immediately but waits until you tell it to commit or void. With inflight_commit_date, you can specify in your request when you want Blnk to automatically commit an inflight transaction for you. This is useful when the inflight transaction starts now, but the final commit should happen at a known future time.
For example, you can reserve funds for a hotel booking today and have Blnk commit the transaction automatically on the check-in date.
Record inflight with commit date
{
    "amount": 100,
    "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,
    "inflight_commit_date": "2024-12-21T01:36:46+01:00"
}
Always format the inflight_commit_date date input as YYYY-MM-DDTHH:MM:SS+00:00 (for example, 2024-04-22T15:28:03+00:00), where +00:00 is the timezone offset. UTC is used by default when you use +00:00.

​
Schedule inflight expiry

A transaction stays inflight until you commit it, void it manually, or it expires. To cap how long funds can remain held inflight, include inflight_expiry_date when you record the transaction.
  • If the transaction is still INFLIGHT after the expiry time, Blnk voids it automatically (same outcome as Update Inflight with void).
  • Creates a new record with VOID status.
  • Resets inflight balances without changing your settled balances.
Record inflight with expiry date
{
    "amount": 100,
    "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,
    "inflight_expiry_date": "2024-12-21T01:36:46+01:00"
}
Always format the inflight_expiry_date date input as YYYY-MM-DDTHH:MM:SS+00:00 (e.g., 2024-04-22T15:28:03+00:00), where +00:00 specifies the timezone. It is UTC by default.
If you use both inflight_commit_date and inflight_expiry_date, set the commit time before the expiry time so Blnk can commit the hold before it would auto-void.

​
Verifying inflight statuses

​
Via Search API

You can verify transaction status using the Search API by querying with the appropriate transaction ID:
Use the queued transaction ID to search for its child transactions.
cURL
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "<queued_transaction_id>",
    "query_by": "meta_data.QUEUED_PARENT_TRANSACTION",
    "filter_by": "status:[APPLIED, VOID]"
  }'

​
Via webhooks

The most reliable way to verify if an inflight transaction has been committed or voided is through webhooks. This approach allows you to receive real-time notifications when the transaction status changes:
1

Add verification reference to metadata

Before creating the inflight transaction, generate a unique verification reference and add it to the transaction’s metadata:
{
    "amount": 100,
    "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,
    "meta_data": {
        "verification_ref": "verify_abc123xyz"
    }
}
2

Handle webhook notifications

When the inflight transaction is committed or voided, Blnk sends a webhook notification. The metadata from the parent transaction is passed down to the child transaction, so you can identify your transaction using the verification reference.
Blnk also adds inflight: true to the transaction’s metadata.
transaction.applied
{
    "transaction_id": "txn_e0f5ab98-bb87-4b09-aefe-839ddb11598b",
    "hook_type": "POST_TRANSACTION",
    "timestamp": "2025-02-23T09:43:49.636219+01:00",
    "data": {
        "precise_amount": 20000,
        "amount": 200,
        "rate": 1,
        "precision": 100,
        "transaction_id": "txn_e0f5ab98-bb87-4b09-aefe-839ddb11598b",
        "parent_transaction": "",
        "source": "bln_7f91a1ae-6073-4b7a-952c-23abf94a6634",
        "destination": "bln_59b83b9c-842c-427f-91eb-43cdeaf5c01a",
        "reference": "4rddddd3dd3rredddddddddde3sddddsdddeddeed",
        "currency": "GBP",
        "description": "Testing inflight/rates issue",
        "status": "APPLIED",
        "hash": "623e05ceb7ca7b02a9318092de7b75d8c668628e2db76c42b621b61055b10b3e",
        "allow_overdraft": true,
        "inflight": false,
        "skip_queue": true,
        "created_at": "2025-02-23T09:43:49.623494+01:00",
        "scheduled_for": "0001-01-01T00:00:00Z",
        "inflight_expiry_date": "0001-01-01T00:00:00Z",
        "inflight_commit_date": "0001-01-01T00:00:00Z",
        "meta_data": {
            "verification_ref": "verify_abc123xyz",
            "inflight": true
        }
    }
}
3

Process webhook in your application

Finally, check each webhook and verify that the verification reference from the webhook matches the specific inflight transaction you’re tracking.
You’re good to go!

​
Inflight for multiple sources/destinations

Multiple sources in Blnk allow you send from multiple sources to a single destination simultaneously, while multiple destinations allow you to send from one source to multiple destinations. Learn more: Multiple Sources and Multiple Destinations.
1

Initiate inflight

When initiating inflight transactions with multiple sources/destinations, enable the inflight feature in your transaction request. Here’s how to structure your request:
Request
{
    // ... other transaction details
    "inflight": true
}
When using multiple sources/destinations, each transaction is recorded separately in the ledger.However, these transactions are linked together through a parent_transaction attribute, which you’ll receive in the response to your transaction request. This parent_transaction helps you track and manage related transactions as a single unit.
2

Update Inflight

To commit or void all transactions at once, call the Update Inflight endpoint and pass the root-level transaction_id from your API response as the path parameter.
cURL
curl -X PUT http://YOUR_BLNK_INSTANCE_URL/transactions/inflight/{parent_transaction} \
  -H 'X-Blnk-Key: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "commit"
  }'

​
Use cases

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.

​
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.