The Bulk Transaction API enables you to process multiple transactions within a single request. It offers two processing options: atomic processing, where all transactions either succeed or fail as a unit, and independent processing, where each transaction is handled separately.
Additionally, the API supports asynchronous processing to efficiently manage large batches of transactions.
When true, either all transactions succeed or all fail. When false, transactions are processed independently.
inflight
Boolean
Yes
When true, transactions are created in INFLIGHT status and require a separate commit. When false, transactions are processed immediately.
run_async
Boolean
No
When true, processing happens in the background and results are delivered via webhook. When false or not provided, processing happens synchronously and results are returned in the response.
When you submit a bulk transaction request, Blnk assigns each transaction in the batch its own unique transaction ID but tags them all with the same parent_transaction (which is your original batch_id).
To retrieve every transaction in that batch:
Copy
POST http://YOUR_BLNK_INSTANCE_URL/search/transactions
{ "event": "bulk_transaction.failed", "data": { "batch_id": "bulk_4192d961-5b0e-46ca-bf2f-9386763057f8", "status": "failed", "error": "failed to queue transaction 2 (Reference: ref_967yg16hhh4q0t0dnsczvud9, Source: bln_a03ef6af-1e5d-46a8-86a9-5fb1f2286f66, Destination: bln_68be0aed-383c-4d27-87db-fb0650093686, Amount: 313333369.18): failed to apply transaction to balances: insufficient funds in source balance. All transactions in this batch have been refunded.", "timestamp": "2025-03-02T19:30:22.43597+01:00" }}
When using atomic: true with inflight: false and run_async: false, if any transaction in the batch fails, all previously processed transactions will be automatically refunded, and you’ll receive an error response like this:
Copy
{ "batch_id": "bulk_4192d961-5b0e-46ca-bf2f-9386763057f8", "error": "failed to queue transaction 1 (Reference: ref001, Source: @account1, Destination: @account2, Amount: 50.00): transaction validation failed: reference ref001 has already been used. All transactions in this batch have been refunded."}
When using atomic: true with run_async: true, if any transaction fails, all transactions will be rolled back, and you’ll receive a webhook notification with an error message containing the rollback status:
Copy
{ "batch_id": "bulk_4192d961-5b0e-46ca-bf2f-9386763057f8", "status": "failed", "error": "failed to queue transaction 2 (Reference: ref002, Source: @account1, Destination: @account2, Amount: 75.50): transaction validation failed: insufficient balance. All transactions in this batch have been refunded.", "timestamp": "2025-03-02T15:30:45Z"}
When using atomic: true with inflight: true, if any transaction in the batch fails during the inflight creation phase, all previously created inflight transactions will be automatically voided, and you’ll receive an error response (or webhook for async) like this:
Copy
{ "batch_id": "bulk_0813d39e-7ead-406b-83de-51eb1975357c", "error": "failed to queue transaction 1 (Reference: ref003, Source: @account1, Destination: @account2, Amount: 25.00): transaction validation failed: reference ref003 has already been used. All transactions in this batch have been voided."}
When using atomic: false, if a transaction in the batch fails, only that transaction and the subsequent transactions in the sequence will fail; all previous transactions that succeeded before the failed one will remain applied in your ledger.
You’ll receive an error response (or webhook for async) like this:
Copy
{ "batch_id": "bulk_2adde6a2-87b9-4ef1-ab10-8c5f1a82083c", "error": "failed to queue transaction 1 (Reference: ref004, Source: @account1, Destination: @account2, Amount: 125.00): transaction validation failed: reference ref004 has already been used. Previous transactions were not rolled back."}
