Learn how to handle bulk transactions in Blnk
Field | Type | Required | Description |
---|---|---|---|
atomic | Boolean | Yes | 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. |
skip_queue | Boolean | No | Defaults to false . When true , transactions bypass the queue system. Learn more: Why we use queueing. |
transactions | Array | Yes | Array of transaction objects. |
run_async
is false:
run_async
is true:
parent_transaction
(which is your original batch_id
).
To retrieve every transaction in that batch:
q
: The batch_id
returned when you created the request.query_by
: Must be set to parent_transaction
.batch_id
.
run_async: true
, the API sends webhook notifications upon completion or failure.
Field | Type | Description |
---|---|---|
event | String | Name of event. Can be bulk_transaction.applied , bulk_transaction.inflight , or bulk_transaction.failed . |
batch_id | String | Specifies the id of the batch transaction. |
status | String | Status of the batch transaction. Can be applied , inflight , or failed . |
transaction_count | String | Number of transactions in the batch. Only included for successful cases. |
error | String | Error message. Only included for failure cases. |
timestamp | String | Specifies the date & time when the batch transaction was completed. |
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:
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:
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:
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:
atomic
is true
, transactions are processed in the order provided in the request.reference
must be unique.run_async
is true
, processing happens in the background and you’ll receive an immediate response with a batch ID.run_async: true
is recommended to avoid timeout issues.