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.
Blnk allows you to move money from multiple sources to a single destination in one transaction. This provides enhanced flexibility for complex money flows and makes tracking and reconciliation easier.

​
Example workflow

Pooling contributions, topping up a wallet from multiple linked accounts, or settling an invoice from more than one internal pot are common use cases for multiple sources. For example, Sarah should receive USD 30,000 into her balance. Alice contributes 10%, Bob sends a fixed $20,000, and Charlie’s contribution uses "left" so whatever remains after the first two legs comes from Charlie automatically. Money movement would look like this: Multiple sources transaction flow Explore the map yourself here
Balance IDAmount
Alicebln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f10% (USD 3,000)
Bobbln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025dUSD 20,000
Charliebln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89bRemaining amount (USD 7,000)
Sarah (Recipient)bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38Total: USD 30,000
When sending from multiple sources, you can only send to one destination.

​
Create multiple sources transaction

Call the Create Transaction endpoint with these fields:
cURL
curl -X POST http://localhost:5001/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "amount": 30000,
    "precision": 100,
    "reference": "ref_001adcfgf",
    "currency": "USD",
    "sources": [
        {
            "identifier": "bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f",
            "distribution": "10%"
        },
        {
            "identifier": "bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d",
            "distribution": "20000"
        },
        {
            "identifier": "bln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89b",
            "distribution": "left"
        }
    ],
    "destination": "bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38",
    "description": "Payment to Sarah"
  }'
FieldDescriptionRequiredType
amountTotal amount to be receivedYesfloat
precisionConverts amount to lowest unit. See Understanding precisionNoint64
referenceUnique transaction referenceYesstring
currencyAsset class code.Yesstring
sourcesArray of source objects with identifier and distribution fieldsYesarray
sources.identifierBalance ID of the source accountYesstring
sources.distributionAmount to send from this source (specific amount, percentage, or “left”)Yesstring
destinationRecipient’s balance IDYesstring
meta_dataCustom transaction dataNoobject
When sending from multiple sources, do not include the source field in your payload. Use the sources array to group the participating balances in your payload.

​
API response structure

When you create a multiple sources transaction, Blnk records one coordinated request and creates separate ledger movements per source—all credited to the single destination. Blnk returns a response containing:
  • A main transaction ID for the overall split transaction. If inflight: true, it can be used to commit or void all transactions at once.
  • A sources array with individual transaction IDs for each source.
Response
{
    "precise_amount": 3000000,
    "amount": 30000,
    "rate": 1,
    "precision": 100,
    "overdraft_limit": 0,
    "transaction_id": "txn_0b59f6e-6c4a-4efa-915c-526f77ef61ab",
    "parent_transaction": "",
    "source": "",
    "reference": "ref_001adcfgf",
    "currency": "USD",
    "description": "txn",
    "status": "QUEUED",
    "hash": "8cfdc0f2562ce30c3728ef624dc29fbd0e4207c77df9220df0c699d45de0eef",
    "allow_overdraft": true,
    "inflight": false,
    "skip_queue": false,
    "atomic": false,
    "sources": [
        {
            "identifier": "@test-2024",
            "distribution": "10%",
            "transaction_id": "txn_59347177-aa7e-d8ad-9f4f-d09628b32ec3"
        },
        {
            "identifier": "@test-21",
            "distribution": "20000",
            "transaction_id": "txn_7ddc8d4f-3b77-4b7d-a37f-240216ab074c"
        },
        {
            "identifier": "@test-218",
            "distribution": "left",
            "transaction_id": "txn_5aad04dd-ed53-4f77-9f01-4916d31fac5f"
        }
    ],
    "destination": "bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38",
    "created_at": "2025-09-18T01:26:30.648049042Z",
    "scheduled_for": "0001-01-01T00:00:00Z",
    "inflight_expiry_date": "0001-01-01T00:00:00Z",
    "meta_data": {
        "QUEUED_PARENT_TRANSACTION": "txn_0b59f6e-6c4a-4efa-915c-526f77ef61ab"
    }
}

​
Retrieving child transactions

You can retrieve all transactions in the split by searching for the main transaction ID in the meta_data.QUEUED_PARENT_TRANSACTION field:
cURL
curl -X POST "http://localhost:5001/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "txn_0b59f6e-6c4a-4efa-915c-526f77ef61ab",
    "query_by": "meta_data.QUEUED_PARENT_TRANSACTION"
  }'
This will return all individual transactions that were created as part of the multiple sources transaction, allowing you to track and manage the complete set of related transactions.

​
Distribution types

You can specify distribution amounts in three ways:
TypeDescriptionExample
Specific amountFixed amount to send"distribution": "20000"
PercentagePercentage of total amount"distribution": "10%"
RemainingLeftover amount after other distributions"distribution": "left"
You can only use "left" once per transaction, and all distributions must sum to the total amount.

​
Using precise_distribution with precise_amount

When a transaction uses precise_amount, use precise_distribution in place of distribution only for sources that specify an exact value. For example:
Example with precise_amount
{
  ...
  "precise_amount": 189207535698279000,
  "sources": [
    {
      "identifier": "bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f",
      "precise_distribution": "37841507139655800"
    },
    {
      "identifier": "bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d",
      "distribution": "20%"
    }
  ]
}
For more information about precision and precise_amount, see Transaction precision.

​
Transaction references

Blnk automatically generates unique references for each transaction record by appending a counter to your original reference (starting from 1). Example: If your reference is ref_001adcfgf, the generated references will be:
  • ref_001adcfgf_1 (first source)
  • ref_001adcfgf_2 (second source)
  • ref_001adcfgf_3 (third source)
This ensures traceability while maintaining connection to the original transaction. Also see:

Multiple destinations

Move money from a single source to multiple destinations in one transaction.

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