Bulk Transactions • Blnk Developer Documentation

Available in version 0.9.0 and later.

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.

Creating bulk transactions

Configure and submit the batch

Call the Bulk Transactions API.

Field	Description
`atomic`	When `true`, either all transactions succeed or all fail. When `false`, transactions are processed independently.
`inflight`	When `true`, transactions are created in `INFLIGHT` status and require a separate commit. When `false`, transactions are processed immediately.
`run_async`	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`	Defaults to `false`. When `true`, transactions bypass the queue and are processed inline in the request. Affects duplicate-reference handling - see Duplicate references.
`transactions`	Array of transaction objects. Max of 10,000 transactions per request.

curl -X POST "http://localhost:5001/transactions/bulk" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "atomic": true,
    "inflight": false,
    "run_async": false,
    "skip_queue": false,
    "transactions": [
      {
        "precise_amount": 35890,
        "precision": 100,
        "reference": "unique_reference_1",
        "description": "Transaction description",
        "currency": "NGN",
        "source": "@source_account",
        "allow_overdraft": true,
        "destination": "@destination_account"
      },
      {
        "precise_amount": 35890,
        "precision": 100,
        "reference": "unique_reference_2",
        "description": "Transaction description",
        "currency": "NGN",
        "source": "@source_account",
        "allow_overdraft": true,
        "destination": "@destination_account"
      }
    ]
  }'

const response = await blnk.Transactions.createBulk({
  atomic: true,
  inflight: false,
  run_async: false,
  skip_queue: false,
  transactions: [
    {
      precise_amount: 35890,
      precision: 100,
      reference: 'unique_reference_1',
      description: 'Transaction description',
      currency: 'NGN',
      source: '@source_account',
      allow_overdraft: true,
      destination: '@destination_account',
    },
    {
      precise_amount: 35890,
      precision: 100,
      reference: 'unique_reference_2',
      description: 'Transaction description',
      currency: 'NGN',
      source: '@source_account',
      allow_overdraft: true,
      destination: '@destination_account',
    },
  ],
});

batch, resp, err := client.Transaction.CreateBulk(blnkgo.CreateBulkTransactionRequest{
  Atomic:    true,
  Inflight:  false,
  RunAsync:  false,
  SkipQueue: false,
  Transactions: []blnkgo.CreateTransactionRequest{
    {
      PreciseAmount:  35890,
      Precision:      100,
      Reference:      "unique_reference_1",
      Description:    "Transaction description",
      Currency:       "NGN",
      Source:         "@source_account",
      Destination:    "@destination_account",
      AllowOverdraft: true,
    },
    {
      PreciseAmount:  35890,
      Precision:      100,
      Reference:      "unique_reference_2",
      Description:    "Transaction description",
      Currency:       "NGN",
      Source:         "@source_account",
      Destination:    "@destination_account",
      AllowOverdraft: true,
    },
  },
})

Confirm the response

Blnk returns a batch_id that identifies the batch. When skip_queue: false, Blnk stores batch_id as the queued parent transaction.Save it. You can use the same ID to retrieve, commit, refund, or void every transaction in the batch without tracking individual child IDs first. See Retrieving transactions in a batch.

Synchronous
Asynchronous

When run_async is false:

Response

{
  "batch_id": "bulk_c62f200b-905f-4983-a349-cadd279234aa",
  "status": "applied",
  "transaction_count": 2
}

On the default queued path, status: "applied" means the bulk request was successfully submitted, not that every child is already APPLIED on balances. Blnk enqueues each item for asynchronous processing.

When run_async is true, Blnk accepts the batch and returns immediately with status: "processing".Processing continues in the background. The HTTP response does not wait for each transaction to finish.Once done, Blnk sends one of the following webhook events with the final outcome.

bulk_transaction.applied
bulk_transaction.inflight
bulk_transaction.failed

See Webhook notifications.

Response

{
  "batch_id": "bulk_c62f200b-905f-4983-a349-cadd279234aa",
  "status": "processing",
  "message": "Bulk transaction processing started"
}

Retrieving transactions in a batch

When you submit a bulk transaction request, Blnk assigns each transaction in the batch its own unique transaction ID and links it to your batch_id:

skip_queue: false (default): child transactions record batch_id in meta_data.QUEUED_PARENT_TRANSACTION.
skip_queue: true: child transactions set parent_transaction to batch_id.

skip_queue: false
skip_queue: true

Filter on meta_data.QUEUED_PARENT_TRANSACTION using Search via database filtering:

curl -X POST "http://localhost:5001/transactions/filter" \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: <api-key>" \
  -d '{
    "filters": [
      {
        "field": "meta_data.QUEUED_PARENT_TRANSACTION",
        "operator": "eq",
        "value": "<batch-id>"
      }
    ]
  }'

const response = await blnk.Search.filter(
  {
    filters: [
      {
        field: 'meta_data.QUEUED_PARENT_TRANSACTION',
        operator: 'eq',
        value: '<batch-id>',
      },
    ],
  },
  'transactions',
);

results, resp, err := client.Transaction.Filter(blnkgo.FilterParams{
  Filters: []blnkgo.Filter{
    {
      Field:    "meta_data.QUEUED_PARENT_TRANSACTION",
      Operator: blnkgo.OpEqual,
      Value:    "<batch-id>",
    },
  },
})

Response

{
  "data": [
    {
      "transaction_id": "txn_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
      "meta_data": {
        "QUEUED_PARENT_TRANSACTION": "bulk_c62f200b-905f-4983-a349-cadd279234aa"
      },
      "status": "APPLIED"
    }
  ]
}

Filter on parent_transaction:

curl -X POST "http://localhost:5001/transactions/filter" \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: <api-key>" \
  -d '{
    "filters": [
      {
        "field": "parent_transaction",
        "operator": "eq",
        "value": "<batch-id>"
      }
    ]
  }'

const response = await blnk.Search.filter(
  {
    filters: [
      {
        field: 'parent_transaction',
        operator: 'eq',
        value: '<batch-id>',
      },
    ],
  },
  'transactions',
);

results, resp, err := client.Transaction.Filter(blnkgo.FilterParams{
  Filters: []blnkgo.Filter{
    {
      Field:    "parent_transaction",
      Operator: blnkgo.OpEqual,
      Value:    "<batch-id>",
    },
  },
})

Response

{
  "data": [
    {
      "transaction_id": "txn_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
      "parent_transaction": "bulk_c62f200b-905f-4983-a349-cadd279234aa",
      "status": "APPLIED"
    }
  ]
}

Replace <batch-id> with the batch_id from the create response. Use the filter field that matches how you submitted the batch.

Handling inflight bulk transactions

To create inflight bulk transactions, set inflight: true in the request body. Blnk ignores any inflight flag passed in the transaction objects and respects the root inflight flag. When set, all transactions in the batch will be processed as INFLIGHT. To commit or void all inflight transactions in a batch, use the batch_id. For independently-created inflight holds, see Bulk commit & void.

curl -X PUT "http://YOUR_BLNK_INSTANCE_URL/transactions/inflight/{batch_id}" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "commit"
  }'

const response = await blnk.Transactions.updateStatus('{batch_id}', {
  status: 'commit',
});

txn, resp, err := client.Transaction.Update("{batch_id}", blnkgo.UpdateStatus{
  Status: blnkgo.InflightStatusCommit,
})

Response

{
  "transaction_id": "bulk_c62f200b-905f-4983-a349-cadd279234aa",
  "status": "APPLIED",
  "parent_transaction": "bulk_c62f200b-905f-4983-a349-cadd279234aa"
}

Webhook notifications

When using run_async: true, the API sends webhook notifications upon completion or failure. The webhooks follow this structure:

{
  "event": "bulk_transaction.applied",
  "data": {
    "batch_id": "bulk_c62f200b-905f-4983-a349-cadd279234aa",
    "status": "applied",
    "transaction_count": 4,       
    "error": "error message",     
    "timestamp": "2025-03-02T15:30:45+01:00"
  }
}

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.

Successful webhook
Failure webhook

{
  "event": "bulk_transaction.applied",
  "data": {
    "batch_id": "bulk_c62f200b-905f-4983-a349-cadd279234aa",
    "status": "applied",
    "transaction_count": 4,
    "timestamp": "2025-03-02T15:30:45+01:00"
  }
}

{
  "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"
  }
}

Usage examples

Synchronous
Asynchronous
Inflight

Process multiple transactions atomically (atomic: true, run_async: false):

curl -X POST "http://localhost:5001/transactions/bulk" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "atomic": true,
    "inflight": false,
    "transactions": [
      {
        "precise_amount": 10000,
        "precision": 100,
        "reference": "tx_001",
        "description": "First transaction",
        "currency": "NGN",
        "source": "@account1",
        "destination": "@account2"
      },
      {
        "precise_amount": 5000,
        "precision": 100,
        "reference": "tx_002",
        "description": "Second transaction",
        "currency": "NGN",
        "source": "@account2",
        "destination": "@account3"
      }
    ]
  }'

const response = await blnk.Transactions.createBulk({
  atomic: true,
  inflight: false,
  transactions: [
    {
      precise_amount: 10000,
      precision: 100,
      reference: 'tx_001',
      description: 'First transaction',
      currency: 'NGN',
      source: '@account1',
      destination: '@account2',
    },
    {
      precise_amount: 5000,
      precision: 100,
      reference: 'tx_002',
      description: 'Second transaction',
      currency: 'NGN',
      source: '@account2',
      destination: '@account3',
    },
  ],
});

batch, resp, err := client.Transaction.CreateBulk(blnkgo.CreateBulkTransactionRequest{
  Atomic:   true,
  Inflight: false,
  Transactions: []blnkgo.CreateTransactionRequest{
    {
      PreciseAmount: 10000,
      Precision:   100,
      Reference:   "tx_001",
      Description: "First transaction",
      Currency:    "NGN",
      Source:      "@account1",
      Destination: "@account2",
    },
    {
      PreciseAmount: 5000,
      Precision:   100,
      Reference:   "tx_002",
      Description: "Second transaction",
      Currency:    "NGN",
      Source:      "@account2",
      Destination: "@account3",
    },
  },
})

Response

{
  "batch_id": "bulk_4192d961-5b0e-46ca-bf2f-9386763057f8",
  "status": "applied",
  "transaction_count": 2
}

Process a large batch in the background (run_async: true). Blnk returns immediately; the final outcome arrives via webhook.

curl -X POST "http://localhost:5001/transactions/bulk" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "atomic": true,
    "inflight": false,
    "run_async": true,
    "transactions": [
      {
        "precise_amount": 10000,
        "precision": 100,
        "reference": "tx_001",
        "description": "First transaction",
        "currency": "NGN",
        "source": "@account1",
        "destination": "@account2"
      },
      {
        "precise_amount": 7500,
        "precision": 100,
        "reference": "tx_999",
        "description": "Last transaction",
        "currency": "NGN",
        "source": "@account5",
        "destination": "@account6"
      }
    ]
  }'

const response = await blnk.Transactions.createBulk({
  atomic: true,
  inflight: false,
  run_async: true,
  transactions: [
    {
      precise_amount: 10000,
      precision: 100,
      reference: 'tx_001',
      description: 'First transaction',
      currency: 'NGN',
      source: '@account1',
      destination: '@account2',
    },
    {
      precise_amount: 7500,
      precision: 100,
      reference: 'tx_999',
      description: 'Last transaction',
      currency: 'NGN',
      source: '@account5',
      destination: '@account6',
    },
  ],
});

batch, resp, err := client.Transaction.CreateBulk(blnkgo.CreateBulkTransactionRequest{
  Atomic:   true,
  Inflight: false,
  RunAsync: true,
  Transactions: []blnkgo.CreateTransactionRequest{
    {
      PreciseAmount: 10000,
      Precision:   100,
      Reference:   "tx_001",
      Description: "First transaction",
      Currency:    "NGN",
      Source:      "@account1",
      Destination: "@account2",
    },
    {
      PreciseAmount: 7500,
      Precision:   100,
      Reference:   "tx_999",
      Description: "Last transaction",
      Currency:    "NGN",
      Source:      "@account5",
      Destination: "@account6",
    },
  },
})

Response

{
  "batch_id": "bulk_c62f200b-905f-4983-a349-cadd279234aa",
  "status": "processing",
  "message": "Bulk transaction processing started"
}

Create inflight batch

Set inflight: true on the bulk request. See Handling inflight bulk transactions.

curl -X POST "http://localhost:5001/transactions/bulk" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "atomic": true,
    "inflight": true,
    "transactions": [
      {
        "precise_amount": 10000,
        "precision": 100,
        "reference": "tx_003",
        "description": "First transaction",
        "currency": "NGN",
        "source": "@account1",
        "destination": "@account2"
      },
      {
        "precise_amount": 5000,
        "precision": 100,
        "reference": "tx_004",
        "description": "Second transaction",
        "currency": "NGN",
        "source": "@account2",
        "destination": "@account3"
      }
    ]
  }'

const response = await blnk.Transactions.createBulk({
  atomic: true,
  inflight: true,
  transactions: [
    {
      precise_amount: 10000,
      precision: 100,
      reference: 'tx_003',
      description: 'First transaction',
      currency: 'NGN',
      source: '@account1',
      destination: '@account2',
    },
    {
      precise_amount: 5000,
      precision: 100,
      reference: 'tx_004',
      description: 'Second transaction',
      currency: 'NGN',
      source: '@account2',
      destination: '@account3',
    },
  ],
});

batch, resp, err := client.Transaction.CreateBulk(blnkgo.CreateBulkTransactionRequest{
  Atomic:   true,
  Inflight: true,
  Transactions: []blnkgo.CreateTransactionRequest{
    {
      PreciseAmount: 10000,
      Precision:   100,
      Reference:   "tx_003",
      Description: "First transaction",
      Currency:    "NGN",
      Source:      "@account1",
      Destination: "@account2",
    },
    {
      PreciseAmount: 5000,
      Precision:   100,
      Reference:   "tx_004",
      Description: "Second transaction",
      Currency:    "NGN",
      Source:      "@account2",
      Destination: "@account3",
    },
  },
})

Response

{
  "batch_id": "bulk_c62f200b-905f-4983-a349-cadd279234aa",
  "status": "inflight",
  "transaction_count": 2
}

Commit the batch

Use the returned batch_id to commit every inflight transaction in the batch:

curl -X PUT "http://localhost:5001/transactions/inflight/bulk_c62f200b-905f-4983-a349-cadd279234aa" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "commit"
  }'

const response = await blnk.Transactions.updateStatus(
  'bulk_c62f200b-905f-4983-a349-cadd279234aa',
  { status: 'commit' },
);

txn, resp, err := client.Transaction.Update(
  "bulk_c62f200b-905f-4983-a349-cadd279234aa",
  blnkgo.UpdateStatus{
    Status: blnkgo.InflightStatusCommit,
  },
)

Error handling

Structured errors are available from Blnk Core 0.15.0 and later.

Bulk endpoints return structured error_detail objects for validation failures. For duplicate references and batch rollbacks, behaviour depends on skip_queue. See API error codes for the full catalogue.

Request validation errors

Blnk returns 400 when the request body fails validation before processing starts.

Code	When it happens
`TXN_BULK_EMPTY`	`transactions` array is empty
`TXN_BULK_LIMIT_EXCEEDED`	More than 10,000 items in `transactions`
`TXN_VALIDATION_ERROR`	A transaction object is null or invalid

For TXN_VALIDATION_ERROR, error_detail.details.index identifies the zero-based position in transactions[]:

400 Bad Request

{
  "error_detail": {
    "code": "TXN_VALIDATION_ERROR",
    "message": "transactions[1]: currency: cannot be blank; destination: either destination or destinations is required, not both.",
    "details": {
      "index": 1
    }
  },
  "errors": "transactions[1]: currency: cannot be blank; destination: either destination or destinations is required, not both."
}

Duplicate references

Duplicate-reference handling depends on whether items go through the queue.

skip_queue: false
skip_queue: true

On the default queued path, duplicate references are deduplicated in the queue and never recorded. The batch still returns 201 with status: "applied" representing the request was successfully submitted:

201 Created

{
  "batch_id": "bulk_847544fb-2616-43be-a188-f6b8c8f20cf2",
  "status": "applied",
  "transaction_count": 2
}

transaction_count reflects items in the request, not necessarily rows created. A deduplicated item produces no REJECTED row and no error.

When skip_queue: true, Blnk validates references inline. A duplicate fails the batch and returns 409 with TXN_DUPLICATE_REFERENCE.For atomic batches, previously applied items in the same request are refunded via _refund child transactions.

409 Conflict

{
  "batch_id": "bulk_305873c0-518a-470c-bf3a-bc3f3e0b562c",
  "error": "failed to queue transaction 2 (Reference: sqdup-17372-existing, Source: bln_b4819533-9570-4770-a1a0-25c191da0557, Destination: bln_34111155-4015-4e84-bf7c-13a60794bf0b, Amount: 4.00): transaction validation failed: reference sqdup-17372-existing has already been used. All transactions in this batch have been refunded.",
  "error_detail": {
    "code": "TXN_DUPLICATE_REFERENCE",
    "message": "failed to queue transaction 2 (Reference: sqdup-17372-existing, Source: bln_b4819533-9570-4770-a1a0-25c191da0557, Destination: bln_34111155-4015-4e84-bf7c-13a60794bf0b, Amount: 4.00): transaction validation failed: reference sqdup-17372-existing has already been used. All transactions in this batch have been refunded."
  }
}

Important notes

When atomic is true, transactions are processed in the order provided in the request.
Each transaction’s reference should be unique. On the default queued path, duplicates are silently deduplicated rather than rejected - see Duplicate references.
When run_async is true, processing happens in the background and you’ll receive an immediate response with a batch ID.
For large transaction batches, using run_async: true is recommended to avoid timeout issues.
Webhook notifications for async processing contain the same detailed error information as synchronous responses, including rollback status.
On the default queued path, status: "applied" means the bulk request was accepted - search by parent_transaction or meta_data.QUEUED_PARENT_TRANSACTION to verify final child statuses.

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.

​Creating bulk transactions

​Retrieving transactions in a batch

​Handling inflight bulk transactions

​Webhook notifications

​Usage examples

​Error handling

​Request validation errors

​Duplicate references

​Important notes

​Need help?

Creating bulk transactions

Retrieving transactions in a batch

Handling inflight bulk transactions

Webhook notifications

Usage examples

Error handling

Request validation errors

Duplicate references

Important notes

Need help?